030d852...master · typeable/servant

.github/workflows/master.yml+1−4

since splitsnapshots

unifiedsplit

@@ -59,9 +59,6 @@ jobs:

59 cabal test all

60

61 - name: Run doctests

62− # doctests are broken on GHC 9 due to compiler bug:

63− # https://gitlab.haskell.org/ghc/ghc/-/issues/19460

64− continue-on-error: ${{ matrix.ghc == '9.0.1' }}

65 run: |

62 run: |

66 # Necessary for doctest to be found in $PATH

63 # Necessary for doctest to be found in $PATH

67 export PATH="$HOME/.cabal/bin:$PATH"

64 export PATH="$HOME/.cabal/bin:$PATH"

@@ -83,7 +80,7 @@ jobs:

83 runs-on: ubuntu-latest

80 runs-on: ubuntu-latest

84 strategy:

81 strategy:

85 matrix:

82 matrix:

86− stack: ["2.7.3"]

83+ stack: ["2.7.5"]

87 ghc: ["8.10.7"]

84 ghc: ["8.10.7"]

88

85

89 steps:

86 steps:

changelog.d/1556new file+81

@@ -0,0 +1,81 @@

1+synopsis: Display capture hints in router layout

2+prs: #1556

3+

4+description: {

5+

6+This PR enhances the `Servant.Server.layout` function, which produces a textual description of the routing layout of an API. More precisely, it changes `<capture>` blocks, so that they display the name and type of the variable being captured instead.

7+

8+Example:

9+

10+For the following API

11+```haskell

12+type API =

13+ "a" :> "d" :> Get '[JSON] NoContent

14+ :<|> "b" :> Capture "x" Int :> Get '[JSON] Bool

15+ :<|> "a" :> "e" :> Get '[JSON] Int

16+```

17+

18+we previously got the following output:

19+

20+```

21+/

22+├─ a/

23+│ ├─ d/

24+│ │ └─•

25+│ └─ e/

26+│ └─•

27+└─ b/

28+ └─ <capture>/

29+ ├─•

30+ ┆

31+ └─•

32+```

33+

34+now we get:

35+

36+```

37+/

38+├─ a/

39+│ ├─ d/

40+│ │ └─•

41+│ └─ e/

42+│ └─•

43+└─ b/

44+ └─ <x::Int>/

45+ ├─•

46+ ┆

47+ └─•

48+```

49+

50+This change is achieved by the introduction of a CaptureHint type, which is passed as an extra argument to the CaptureRouter and CaptureAllRouter constructors for the Router' type.

51+CaptureHint values are then used in routerLayout, to display the name and type of captured values, instead of just `<capture>` previously.

52+

53+N.B.:

54+Because the choice smart constructor for routers can aggregate Capture combinators with different capture hints, the Capture*Router constructors actually take a list of CaptureHint, instead of a single one.

55+

56+This PR also introduces Spec tests for the routerLayout function.

57+

58+Warning:

59+This change is potentially breaking, because it adds the constraint `Typeable a` to all types that are to be captured. Because all types are typeable since GHC 7.10, this is not as bad as it sounds ; it only break expressions where `a` is quantified in an expression with `Capture a`.

60+In those cases, the fix is easy: it suffices to add `Typeable a` to the left-hand side of the quantification constraint.

61+

62+For instance, the following code will no longer compile:

63+```haskell

64+type MyAPI a = Capture "foo" a :> Get '[JSON] ()

65+

66+myServer :: forall a. Server (MyAPI a)

67+myServer = const $ return ()

68+

69+myApi :: forall a. Proxy (MyAPI a)

70+myApi = Proxy

71+

72+app :: forall a. (FromHttpApiData a) => Application

73+app = serve (myApi @a) (myServer @a)

74+```

75+

76+Indeed, `app` should be replaced with:

77+```haskell

78+app :: forall a. (FromHttpApiData a, Typeable a) => Application

79+app = serve (myApi @a) (myServer @a)

80+```

81+}

changelog.d/1569new file+13

@@ -0,0 +1,13 @@

1+synopsis: Encode captures using toEncodedUrlPiece

2+prs: #1569

3+issues: #1511

4+

5+description: {

6+The `servant-client` library now makes direct use of `toEncodedUrlPiece` from `ToHttpApiData`

7+to encode captured values when building the request path. It gives user freedom to implement

8+URL-encoding however they need.

9+

10+Previous behavior was to use `toUrlPiece` and URL-encode its output using `toEncodedUrlPiece`

11+from the `Text` instance of `ToHttpApiData`. The issue with this approach is that

12+`ToHttpApiData Text` is overly zealous and also encodes characters, such as `*`, which are perfectly valid in a URL.

13+}

changelog.d/1580new file+12

@@ -0,0 +1,12 @@

1+synopsis: Allow IO in validationKeys

2+prs: #1580

3+issues: #1579

4+

5+description: {

6+

7+Currently validationKeys are a fixed JWKSet. This does not work with OIDC

8+providers such as AWS Cognito or Okta, which regularly fetching jwks_uri to

9+discover new and expired keys.

10+

11+This change alters the type of validationKeys from JWKSet to IO JWKSet.

12+}

changelog.d/1589new file+2

@@ -0,0 +1,2 @@

1+synopsis: Only include question mark for nonempty query strings

2+prs: 1589

changelog.d/1595new file+2

@@ -0,0 +1,2 @@

1+synopsis: Run ClientEnv's makeClientRequest in IO.

2+prs: #1595

doc/cookbook/using-free-client/UsingFreeClient.lhs+1−1

@@ -119,7 +119,7 @@ Now we can use `servant-client`'s internals to convert servant's `Request`

119to http-client's `Request`, and we can inspect it:

120

121```haskell

122− let req' = I.defaultMakeClientRequest burl req

122+ req' <- I.defaultMakeClientRequest burl req

123 putStrLn $ "Making request: " ++ show req'

124```

125

servant-auth/servant-auth-client/servant-auth-client.cabal+2−2

@@ -50,7 +50,7 @@ test-suite spec

50 test

51 default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

52 ghc-options: -Wall

53− build-tool-depends: hspec-discover:hspec-discover >=2.5.5 && <2.9

53+ build-tool-depends: hspec-discover:hspec-discover >=2.5.5 && <2.10

54

55 -- dependencies with bounds inherited from the library stanza

56 build-depends:

@@ -62,7 +62,7 @@ test-suite spec

62

63 -- test dependencies

64 build-depends:

65− hspec >= 2.5.5 && < 2.9

65+ hspec >= 2.5.5 && < 2.10

66 , QuickCheck >= 2.11.3 && < 2.15

67 , aeson >= 1.3.1.1 && < 3

68 , bytestring >= 0.10.6.0 && < 0.12

servant-auth/servant-auth-docs/servant-auth-docs.cabal+2−2

@@ -64,7 +64,7 @@ test-suite spec

64 test

65 default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

66 ghc-options: -Wall

67− build-tool-depends: hspec-discover:hspec-discover >=2.5.5 && <2.9

67+ build-tool-depends: hspec-discover:hspec-discover >=2.5.5 && <2.10

68

69 -- dependencies with bounds inherited from the library stanza

70 build-depends:

@@ -78,7 +78,7 @@ test-suite spec

78 -- test dependencies

79 build-depends:

80 servant-auth-docs

81− , hspec >= 2.5.5 && < 2.9

81+ , hspec >= 2.5.5 && < 2.10

82 , QuickCheck >= 2.11.3 && < 2.15

83

84 default-language: Haskell2010

servant-auth/servant-auth-server/servant-auth-server.cabal+3−3

@@ -102,7 +102,7 @@ test-suite spec

102 test

103 default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

104 ghc-options: -Wall

105− build-tool-depends: hspec-discover:hspec-discover >=2.5.5 && <2.8

105+ build-tool-depends: hspec-discover:hspec-discover >=2.5.5 && <2.10

106

107 -- dependencies with bounds inherited from the library stanza

108 build-depends:

@@ -123,10 +123,10 @@ test-suite spec

123 -- test dependencies

124 build-depends:

125 servant-auth-server

126− , hspec >= 2.5.5 && < 2.8

126+ , hspec >= 2.5.5 && < 2.10

127 , QuickCheck >= 2.11.3 && < 2.15

128 , http-client >= 0.5.13.1 && < 0.8

129− , lens-aeson >= 1.0.2 && < 1.2

129+ , lens-aeson >= 1.0.2 && < 1.3

130 , warp >= 3.2.25 && < 3.4

131 , wreq >= 0.5.2.1 && < 0.6

132 other-modules:

servant-auth/servant-auth-server/src/Servant/Auth/Server/Internal/ConfigTypes.hs+2−2

@@ -33,7 +33,7 @@ data JWTSettings = JWTSettings

33 -- | Algorithm used to sign JWT.

34 , jwtAlg :: Maybe Jose.Alg

35 -- | Keys used to validate JWT.

36− , validationKeys :: Jose.JWKSet

36+ , validationKeys :: IO Jose.JWKSet

37 -- | An @aud@ predicate. The @aud@ is a string or URI that identifies the

38 -- intended recipient of the JWT.

39 , audienceMatches :: Jose.StringOrURI -> IsMatch

@@ -44,7 +44,7 @@ defaultJWTSettings :: Jose.JWK -> JWTSettings

44defaultJWTSettings k = JWTSettings

45 { signingKey = k

46 , jwtAlg = Nothing

47− , validationKeys = Jose.JWKSet [k]

47+ , validationKeys = pure $ Jose.JWKSet [k]

48 , audienceMatches = const Matches }

49

50-- | The policies to use when generating cookies.

servant-auth/servant-auth-server/src/Servant/Auth/Server/Internal/JWT.hs+4−3

@@ -58,14 +58,15 @@ makeJWT v cfg expiry = runExceptT $ do

58

59verifyJWT :: FromJWT a => JWTSettings -> BS.ByteString -> IO (Maybe a)

60verifyJWT jwtCfg input = do

61+ keys <- validationKeys jwtCfg

61− verifiedJWT <- liftIO $ runExceptT $ do

62+ verifiedJWT <- runExceptT $ do

62 unverifiedJWT <- Jose.decodeCompact (BSL.fromStrict input)

63 unverifiedJWT <- Jose.decodeCompact (BSL.fromStrict input)

63 Jose.verifyClaims

64 Jose.verifyClaims

64 (jwtSettingsToJwtValidationSettings jwtCfg)

65 (jwtSettingsToJwtValidationSettings jwtCfg)

65− (validationKeys jwtCfg)

66+ keys

66 unverifiedJWT

67 unverifiedJWT

67 return $ case verifiedJWT of

68 return $ case verifiedJWT of

68 Left (_ :: Jose.JWTError) -> Nothing

69 Left (_ :: Jose.JWTError) -> Nothing

69 Right v -> case decodeJWT v of

70 Right v -> case decodeJWT v of

70 Left _ -> Nothing

71 Left _ -> Nothing

71− Right v' -> Just v'

72+ Right v' -> Just v'

servant-auth/servant-auth-swagger/servant-auth-swagger.cabal+3−7

@@ -31,15 +31,13 @@ library

31 default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

32 ghc-options: -Wall

33 build-depends:

34− base >= 4.10 && < 4.16

34+ base >= 4.10 && < 4.17

35 , text >= 1.2.3.0 && < 2.1

36 , servant-swagger >= 1.1.5 && < 2

37 , swagger2 >= 2.2.2 && < 3

38 , servant >= 0.13 && < 0.20

39 , servant-auth == 0.4.*

40 , lens >= 4.16.1 && < 5.2

41− if impl(ghc >= 9)

42− buildable: False

43 exposed-modules:

41 exposed-modules:

44 Servant.Auth.Swagger

42 Servant.Auth.Swagger

45 default-language: Haskell2010

43 default-language: Haskell2010

@@ -51,7 +49,7 @@ test-suite spec

51 test

49 test

52 default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

50 default-extensions: ConstraintKinds DataKinds DefaultSignatures DeriveFoldable DeriveFunctor DeriveGeneric DeriveTraversable FlexibleContexts FlexibleInstances FunctionalDependencies GADTs KindSignatures MultiParamTypeClasses OverloadedStrings RankNTypes ScopedTypeVariables TypeFamilies TypeOperators

53 ghc-options: -Wall

51 ghc-options: -Wall

54− build-tool-depends: hspec-discover:hspec-discover >= 2.5.5 && <2.9

52+ build-tool-depends: hspec-discover:hspec-discover >= 2.5.5 && <2.10

55 -- dependencies with bounds inherited from the library stanza

53 -- dependencies with bounds inherited from the library stanza

56 build-depends:

54 build-depends:

57 base

55 base

@@ -61,13 +59,11 @@ test-suite spec

61 , servant

59 , servant

62 , servant-auth

60 , servant-auth

63 , lens

61 , lens

64− if impl(ghc >= 9)

65− buildable: False

66

62

67 -- test dependencies

63 -- test dependencies

68 build-depends:

64 build-depends:

69 servant-auth-swagger

65 servant-auth-swagger

70− , hspec >= 2.5.5 && < 2.9

66+ , hspec >= 2.5.5 && < 2.10

71 , QuickCheck >= 2.11.3 && < 2.15

67 , QuickCheck >= 2.11.3 && < 2.15

72 other-modules:

68 other-modules:

73 Servant.Auth.SwaggerSpec

69 Servant.Auth.SwaggerSpec

servant-client-core/servant-client-core.cabal+2−2

@@ -104,8 +104,8 @@ test-suite spec

104 -- Additional dependencies

105 build-depends:

106 deepseq >= 1.4.2.0 && < 1.5

107− , hspec >= 2.6.0 && < 2.9

107+ , hspec >= 2.6.0 && < 2.10

108 , QuickCheck >= 2.12.6.1 && < 2.15

109

110 build-tool-depends:

111− hspec-discover:hspec-discover >= 2.6.0 && <2.9

111+ hspec-discover:hspec-discover >= 2.6.0 && <2.10

servant-client-core/src/Servant/Client/Core/HasClient.hs+3−3

@@ -208,7 +208,7 @@ instance (KnownSymbol capture, ToHttpApiData a, HasClient m api)

208 clientWithRoute pm (Proxy :: Proxy api)

209 (appendToPath p req)

210

211− where p = (toUrlPiece val)

211+ where p = toEncodedUrlPiece val

212

213 hoistClientMonad pm _ f cl = \a ->

214 hoistClientMonad pm (Proxy :: Proxy api) f (cl a)

@@ -243,7 +243,7 @@ instance (KnownSymbol capture, ToHttpApiData a, HasClient m sublayout)

243 clientWithRoute pm (Proxy :: Proxy sublayout)

244 (foldl' (flip appendToPath) req ps)

245

246− where ps = map (toUrlPiece) vals

246+ where ps = map toEncodedUrlPiece vals

247

248 hoistClientMonad pm _ f cl = \as ->

249 hoistClientMonad pm (Proxy :: Proxy sublayout) f (cl as)

@@ -740,7 +740,7 @@ instance (KnownSymbol path, HasClient m api) => HasClient m (path :> api) where

740 clientWithRoute pm (Proxy :: Proxy api)

741 (appendToPath p req)

742

743− where p = pack $ symbolVal (Proxy :: Proxy path)

743+ where p = toEncodedUrlPiece $ pack $ symbolVal (Proxy :: Proxy path)

744

745 hoistClientMonad pm _ f cl = hoistClientMonad pm (Proxy :: Proxy api) f cl

746

servant-client-core/src/Servant/Client/Core/Request.hs+10−6

@@ -34,6 +34,8 @@ import Data.Bifunctor

34import Data.Bitraversable

35 (Bitraversable (..), bifoldMapDefault, bimapDefault)

36import qualified Data.ByteString as BS

37+import Data.ByteString.Builder

38+ (Builder)

37import qualified Data.ByteString.Builder as Builder

39import qualified Data.ByteString.Builder as Builder

38import qualified Data.ByteString.Lazy as LBS

40import qualified Data.ByteString.Lazy as LBS

39import qualified Data.Sequence as Seq

41import qualified Data.Sequence as Seq

@@ -49,9 +51,9 @@ import Network.HTTP.Media

49 (MediaType)

51 (MediaType)

50import Network.HTTP.Types

52import Network.HTTP.Types

51 (Header, HeaderName, HttpVersion (..), Method, QueryItem,

53 (Header, HeaderName, HttpVersion (..), Method, QueryItem,

52− http11, methodGet)

54+ http11, methodGet, urlEncodeBuilder)

53import Servant.API

55import Servant.API

54− (ToHttpApiData, toEncodedUrlPiece, toHeader, SourceIO)

56+ (ToHttpApiData, toEncodedUrlPiece, toQueryParam, toHeader, SourceIO)

55

57

56import Servant.Client.Core.Internal (mediaTypeRnf)

58import Servant.Client.Core.Internal (mediaTypeRnf)

57

59

@@ -112,7 +114,7 @@ instance (NFData path, NFData body) => NFData (RequestF body path) where

112 rnfB Nothing = ()

114 rnfB Nothing = ()

113 rnfB (Just (b, mt)) = rnf b `seq` mediaTypeRnf mt

115 rnfB (Just (b, mt)) = rnf b `seq` mediaTypeRnf mt

114

116

115−type Request = RequestF RequestBody Builder.Builder

117+type Request = RequestF RequestBody Builder

116

118

117-- | The request body. R replica of the @http-client@ @RequestBody@.

119-- | The request body. R replica of the @http-client@ @RequestBody@.

118data RequestBody

120data RequestBody

@@ -145,9 +147,10 @@ defaultRequest = Request

145

147

146-- | Append extra path to the request being constructed.

148-- | Append extra path to the request being constructed.

147--

149--

150+-- Warning: This function assumes that the path fragment is already URL-encoded.

148−appendToPath :: Text -> Request -> Request

151+appendToPath :: Builder -> Request -> Request

149appendToPath p req

152appendToPath p req

150− = req { requestPath = requestPath req <> "/" <> toEncodedUrlPiece p }

153+ = req { requestPath = requestPath req <> "/" <> p }

151

154

152-- | Append a query parameter to the request being constructed.

155-- | Append a query parameter to the request being constructed.

153--

156--

@@ -162,7 +165,8 @@ appendToQueryString pname pvalue req

162-- | Encode a query parameter value.

165-- | Encode a query parameter value.

163--

166--

164encodeQueryParamValue :: ToHttpApiData a => a -> BS.ByteString

167encodeQueryParamValue :: ToHttpApiData a => a -> BS.ByteString

165−encodeQueryParamValue = LBS.toStrict . Builder.toLazyByteString . toEncodedUrlPiece

168+encodeQueryParamValue = LBS.toStrict . Builder.toLazyByteString

169+ . urlEncodeBuilder True . encodeUtf8 . toQueryParam

166

170

167-- | Add header to the request being constructed.

171-- | Add header to the request being constructed.

168--

172--

servant-client/servant-client.cabal+2−2

@@ -124,7 +124,7 @@ test-suite spec

124 -- Additional dependencies

125 build-depends:

126 entropy >= 0.4.1.3 && < 0.5

127− , hspec >= 2.6.0 && < 2.9

127+ , hspec >= 2.6.0 && < 2.10

128 , HUnit >= 1.6.0.0 && < 1.7

129 , network >= 2.8.0.0 && < 3.2

130 , QuickCheck >= 2.12.6.1 && < 2.15

@@ -133,7 +133,7 @@ test-suite spec

133 , tdigest >= 0.2 && < 0.3

134

135 build-tool-depends:

136− hspec-discover:hspec-discover >= 2.6.0 && < 2.9

136+ hspec-discover:hspec-discover >= 2.6.0 && < 2.10

137

138test-suite readme

139 type: exitcode-stdio-1.0

servant-client/src/Servant/Client/Internal/HttpClient.hs+8−7

@@ -24,7 +24,7 @@ import Control.Monad

24import Control.Monad.Base

25 (MonadBase (..))

26import Control.Monad.Catch

27− (MonadCatch, MonadThrow)

27+ (MonadCatch, MonadThrow, MonadMask)

28import Control.Monad.Error.Class

29 (MonadError (..))

30import Control.Monad.IO.Class

@@ -80,7 +80,7 @@ data ClientEnv

80 { manager :: Client.Manager

81 , baseUrl :: BaseUrl

82 , cookieJar :: Maybe (TVar Client.CookieJar)

83− , makeClientRequest :: BaseUrl -> Request -> Client.Request

83+ , makeClientRequest :: BaseUrl -> Request -> IO Client.Request

84 -- ^ this function can be used to customize the creation of @http-client@ requests from @servant@ requests. Default value: 'defaultMakeClientRequest'

85 -- Note that:

86 -- 1. 'makeClientRequest' exists to allow overriding operational semantics e.g. 'responseTimeout' per request,

@@ -136,7 +136,7 @@ newtype ClientM a = ClientM

136 { unClientM :: ReaderT ClientEnv (ExceptT ClientError IO) a }

137 deriving ( Functor, Applicative, Monad, MonadIO, Generic

138 , MonadReader ClientEnv, MonadError ClientError, MonadThrow

139− , MonadCatch)

139+ , MonadCatch, MonadMask)

140

141instance MonadBase IO ClientM where

142 liftBase = ClientM . liftBase

@@ -162,7 +162,7 @@ runClientM cm env = runExceptT $ flip runReaderT env $ unClientM cm

162performRequest :: Maybe [Status] -> Request -> ClientM Response

163performRequest acceptStatus req = do

164 ClientEnv m burl cookieJar' createClientRequest <- ask

165− let clientRequest = createClientRequest burl req

165+ clientRequest <- liftIO $ createClientRequest burl req

166 request <- case cookieJar' of

167 Nothing -> pure clientRequest

168 Just cj -> liftIO $ do

@@ -229,8 +229,8 @@ clientResponseToResponse f r = Response

229-- | Create a @http-client@ 'Client.Request' from a @servant@ 'Request'

230-- The 'Client.host', 'Client.path' and 'Client.port' fields are extracted from the 'BaseUrl'

231-- otherwise the body, headers and query string are derived from the @servant@ 'Request'

232−defaultMakeClientRequest :: BaseUrl -> Request -> Client.Request

232+defaultMakeClientRequest :: BaseUrl -> Request -> IO Client.Request

233−defaultMakeClientRequest burl r = Client.defaultRequest

233+defaultMakeClientRequest burl r = return Client.defaultRequest

234 { Client.method = requestMethod r

235 , Client.host = fromString $ baseUrlHost burl

236 , Client.port = baseUrlPort burl

@@ -289,7 +289,8 @@ defaultMakeClientRequest burl r = Client.defaultRequest

289 Https -> True

290

291 -- Query string builder which does not do any encoding

292+ buildQueryString [] = mempty

292− buildQueryString = ("?" <>) . foldl' addQueryParam mempty

293+ buildQueryString qps = "?" <> foldl' addQueryParam mempty qps

293

294

294 addQueryParam qs (k, v) =

295 addQueryParam qs (k, v) =

295 qs <> (if BS.null qs then mempty else "&") <> urlEncode True k <> foldMap ("=" <>) v

296 qs <> (if BS.null qs then mempty else "&") <> urlEncode True k <> foldMap ("=" <>) v

servant-client/src/Servant/Client/Internal/HttpClient/Streaming.hs+2−2

@@ -140,7 +140,7 @@ performRequest :: Maybe [Status] -> Request -> ClientM Response

140performRequest acceptStatus req = do

141 -- TODO: should use Client.withResponse here too

142 ClientEnv m burl cookieJar' createClientRequest <- ask

143− let clientRequest = createClientRequest burl req

143+ clientRequest <- liftIO $ createClientRequest burl req

144 request <- case cookieJar' of

145 Nothing -> pure clientRequest

146 Just cj -> liftIO $ do

@@ -177,7 +177,7 @@ performWithStreamingRequest req k = do

177 m <- asks manager

178 burl <- asks baseUrl

179 createClientRequest <- asks makeClientRequest

180− let request = createClientRequest burl req

180+ request <- liftIO $ createClientRequest burl req

181 ClientM $ lift $ lift $ Codensity $ \k1 ->

182 Client.withResponse request m $ \res -> do

183 let status = Client.responseStatus res

servant-client/test/Servant/ClientTestUtils.hs+13−1

@@ -160,6 +160,7 @@ type Api =

160 WithStatus 301 Text]

161 :<|> "uverb-get-created" :> UVerb 'GET '[PlainText] '[WithStatus 201 Person]

162 :<|> NamedRoutes RecordRoutes

163+ :<|> "captureVerbatim" :> Capture "someString" Verbatim :> Get '[PlainText] Text

163

164

164api :: Proxy Api

165api :: Proxy Api

165api = Proxy

166api = Proxy

@@ -214,7 +215,8 @@ getRoot

214 :<|> EmptyClient

215 :<|> EmptyClient

215 :<|> uverbGetSuccessOrRedirect

216 :<|> uverbGetSuccessOrRedirect

216 :<|> uverbGetCreated

217 :<|> uverbGetCreated

217− :<|> recordRoutes = client api

218+ :<|> recordRoutes

219+ :<|> captureVerbatim = client api

218

220

219server :: Application

221server :: Application

220server = serve api (

222server = serve api (

@@ -259,6 +261,7 @@ server = serve api (

259 { something = pure ["foo", "bar", "pweet"]

261 { something = pure ["foo", "bar", "pweet"]

260 }

262 }

261 }

263 }

264+ :<|> pure . decodeUtf8 . unVerbatim

262 )

265 )

263

266

264-- * api for testing failures

267-- * api for testing failures

@@ -370,3 +373,12 @@ instance ToHttpApiData UrlEncodedByteString where

370

373

371instance FromHttpApiData UrlEncodedByteString where

374instance FromHttpApiData UrlEncodedByteString where

372 parseUrlPiece = pure . UrlEncodedByteString . HTTP.urlDecode True . encodeUtf8

375 parseUrlPiece = pure . UrlEncodedByteString . HTTP.urlDecode True . encodeUtf8

376+

377+newtype Verbatim = Verbatim { unVerbatim :: ByteString }

378+

379+instance ToHttpApiData Verbatim where

380+ toEncodedUrlPiece = byteString . unVerbatim

381+ toUrlPiece = decodeUtf8 . unVerbatim

382+

383+instance FromHttpApiData Verbatim where

384+ parseUrlPiece = pure . Verbatim . encodeUtf8

servant-client/test/Servant/SuccessSpec.hs+11−1

@@ -36,6 +36,8 @@ import Data.Maybe

36import Data.Monoid ()

37import Data.Text

38 (Text)

39+import Data.Text.Encoding

40+ (encodeUtf8)

39import qualified Network.HTTP.Client as C

41import qualified Network.HTTP.Client as C

40import qualified Network.HTTP.Types as HTTP

42import qualified Network.HTTP.Types as HTTP

41import Test.Hspec

43import Test.Hspec

@@ -160,7 +162,8 @@ successSpec = beforeAll (startWaiApp server) $ afterAll endWaiApp $ do

160 mgr <- C.newManager C.defaultManagerSettings

162 mgr <- C.newManager C.defaultManagerSettings

161 -- In proper situation, extra headers should probably be visible in API type.

163 -- In proper situation, extra headers should probably be visible in API type.

162 -- However, testing for response timeout is difficult, so we test with something which is easy to observe

164 -- However, testing for response timeout is difficult, so we test with something which is easy to observe

163− let createClientRequest url r = (defaultMakeClientRequest url r) { C.requestHeaders = [("X-Added-Header", "XXX")] }

165+ let createClientRequest url r = fmap (\req -> req { C.requestHeaders = [("X-Added-Header", "XXX")] })

166+ (defaultMakeClientRequest url r)

164 clientEnv = (mkClientEnv mgr baseUrl) { makeClientRequest = createClientRequest }

167 clientEnv = (mkClientEnv mgr baseUrl) { makeClientRequest = createClientRequest }

165 res <- runClientM (getRawSuccessPassHeaders HTTP.methodGet) clientEnv

168 res <- runClientM (getRawSuccessPassHeaders HTTP.methodGet) clientEnv

166 case res of

169 case res of

@@ -196,3 +199,10 @@ successSpec = beforeAll (startWaiApp server) $ afterAll endWaiApp $ do

196 case eitherResponse of

199 case eitherResponse of

197 Left clientError -> fail $ show clientError

200 Left clientError -> fail $ show clientError

198 Right response -> matchUnion response `shouldBe` Just (WithStatus @201 carol)

201 Right response -> matchUnion response `shouldBe` Just (WithStatus @201 carol)

202+

203+ it "encodes URL pieces following ToHttpApiData instance" $ \(_, baseUrl) -> do

204+ let textOrig = "*"

205+ eitherResponse <- runClient (captureVerbatim $ Verbatim $ encodeUtf8 textOrig) baseUrl

206+ case eitherResponse of

207+ Left clientError -> fail $ show clientError

208+ Right textBack -> textBack `shouldBe` textOrig

servant-docs/src/Servant/Docs/Internal.hs+4

@@ -62,6 +62,7 @@ import GHC.TypeLits

62import Servant.API

63import Servant.API.ContentTypes

64import Servant.API.TypeLevel

65+import Servant.API.Generic

65

66

66import qualified Data.Universe.Helpers as U

67import qualified Data.Universe.Helpers as U

67

68

@@ -1150,6 +1151,9 @@ instance (ToAuthInfo (BasicAuth realm usr), HasDocs api) => HasDocs (BasicAuth r

1150 authProxy = Proxy :: Proxy (BasicAuth realm usr)

1151 authProxy = Proxy :: Proxy (BasicAuth realm usr)

1151 action' = over authInfo (|> toAuthInfo authProxy) action

1152 action' = over authInfo (|> toAuthInfo authProxy) action

1152

1153

1154+instance HasDocs (ToServantApi api) => HasDocs (NamedRoutes api) where

1155+ docsFor Proxy = docsFor (Proxy :: Proxy (ToServantApi api))

1156+

1153-- ToSample instances for simple types

1157-- ToSample instances for simple types

1154instance ToSample NoContent

1158instance ToSample NoContent

1155instance ToSample Bool

1159instance ToSample Bool

servant-foreign/servant-foreign.cabal+2−2

@@ -74,7 +74,7 @@ test-suite spec

74

75 -- Additional dependencies

76 build-depends:

77− hspec >= 2.6.0 && <2.9

77+ hspec >= 2.6.0 && <2.10

78 build-tool-depends:

79− hspec-discover:hspec-discover >=2.6.0 && <2.9

79+ hspec-discover:hspec-discover >=2.6.0 && <2.10

80 default-language: Haskell2010

servant-http-streams/servant-http-streams.cabal+2−2

@@ -112,7 +112,7 @@ test-suite spec

112 -- Additional dependencies

113 build-depends:

114 entropy >= 0.4.1.3 && < 0.5

115− , hspec >= 2.6.0 && < 2.9

115+ , hspec >= 2.6.0 && < 2.10

116 , HUnit >= 1.6.0.0 && < 1.7

117 , network >= 2.8.0.0 && < 3.2

118 , QuickCheck >= 2.12.6.1 && < 2.15

@@ -121,7 +121,7 @@ test-suite spec

121 , tdigest >= 0.2 && < 0.3

122

123 build-tool-depends:

124− hspec-discover:hspec-discover >= 2.6.0 && < 2.9

124+ hspec-discover:hspec-discover >= 2.6.0 && < 2.10

125

126test-suite readme

127 type: exitcode-stdio-1.0

servant-server/servant-server.cabal+3−3

@@ -72,7 +72,7 @@ library

72 -- Servant dependencies

73 -- strict dependency as we re-export 'servant' things.

74 build-depends:

75− servant >= 0.19

75+ servant >= 0.19 && < 0.20

76 , http-api-data >= 0.4.1 && < 0.4.4

77

78 -- Other dependencies: Lower bound around what is in the latest Stackage LTS.

@@ -159,7 +159,7 @@ test-suite spec

159 build-depends:

160 aeson >= 1.4.1.0 && < 3

161 , directory >= 1.3.0.0 && < 1.4

162− , hspec >= 2.6.0 && < 2.9

162+ , hspec >= 2.6.0 && < 2.10

163 , hspec-wai >= 0.10.1 && < 0.12

164 , QuickCheck >= 2.12.6.1 && < 2.15

165 , should-not-typecheck >= 2.1.0 && < 2.2

@@ -167,4 +167,4 @@ test-suite spec

167 , wai-extra >= 3.0.24.3 && < 3.2

168

169 build-tool-depends:

170− hspec-discover:hspec-discover >= 2.6.0 && <2.9

170+ hspec-discover:hspec-discover >= 2.6.0 && <2.10

servant-server/src/Servant/Server.hs+3−2

@@ -235,7 +235,7 @@ hoistServer p = hoistServerWithContext p (Proxy :: Proxy '[])

235-- > │ └─ e/

236-- > │ └─•

237-- > ├─ b/

238−-- > │ └─ <capture>/

238+-- > │ └─ <x::Int>/

239-- > │ ├─•

240-- > │ ┆

241-- > │ └─•

@@ -252,7 +252,8 @@ hoistServer p = hoistServerWithContext p (Proxy :: Proxy '[])

252--

253-- [@─•@] Leaves reflect endpoints.

254--

255−-- [@\<capture\>/@] This is a delayed capture of a path component.

255+-- [@\<x::Int\>/@] This is a delayed capture of a single

256+-- path component named @x@, of expected type @Int@.

256--

257--

257-- [@\<raw\>@] This is a part of the API we do not know anything about.

258-- [@\<raw\>@] This is a part of the API we do not know anything about.

258--

259--

servant-server/src/Servant/Server/Internal.hs+6−4

@@ -173,7 +173,7 @@ instance (HasServer a context, HasServer b context) => HasServer (a :<|> b) cont

173-- > server = getBook

174-- > where getBook :: Text -> Handler Book

175-- > getBook isbn = ...

176−instance (KnownSymbol capture, FromHttpApiData a

176+instance (KnownSymbol capture, FromHttpApiData a, Typeable a

177 , HasServer api context, SBoolI (FoldLenient mods)

178 , HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters

179 )

@@ -185,7 +185,7 @@ instance (KnownSymbol capture, FromHttpApiData a

185 hoistServerWithContext _ pc nt s = hoistServerWithContext (Proxy :: Proxy api) pc nt . s

186

187 route Proxy context d =

188− CaptureRouter $

188+ CaptureRouter [hint] $

189 route (Proxy :: Proxy api)

190 context

191 (addCapture d $ \ txt -> withRequest $ \ request ->

@@ -197,6 +197,7 @@ instance (KnownSymbol capture, FromHttpApiData a

197 where

198 rep = typeRep (Proxy :: Proxy Capture')

199 formatError = urlParseErrorFormatter $ getContextEntry (mkContextWithErrorFormatter context)

200+ hint = CaptureHint (T.pack $ symbolVal $ Proxy @capture) (typeRep (Proxy :: Proxy a))

200

201

201-- | If you use 'CaptureAll' in one of the endpoints for your API,

202-- | If you use 'CaptureAll' in one of the endpoints for your API,

202-- this automatically requires your server-side handler to be a

203-- this automatically requires your server-side handler to be a

@@ -215,7 +216,7 @@ instance (KnownSymbol capture, FromHttpApiData a

215-- > server = getSourceFile

216-- > server = getSourceFile

216-- > where getSourceFile :: [Text] -> Handler Book

217-- > where getSourceFile :: [Text] -> Handler Book

217-- > getSourceFile pathSegments = ...

218-- > getSourceFile pathSegments = ...

218−instance (KnownSymbol capture, FromHttpApiData a

219+instance (KnownSymbol capture, FromHttpApiData a, Typeable a

219 , HasServer api context

220 , HasServer api context

220 , HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters

221 , HasContextEntry (MkContextWithErrorFormatter context) ErrorFormatters

221 )

222 )

@@ -227,7 +228,7 @@ instance (KnownSymbol capture, FromHttpApiData a

227 hoistServerWithContext _ pc nt s = hoistServerWithContext (Proxy :: Proxy api) pc nt . s

228 hoistServerWithContext _ pc nt s = hoistServerWithContext (Proxy :: Proxy api) pc nt . s

228

229

229 route Proxy context d =

230 route Proxy context d =

230− CaptureAllRouter $

231+ CaptureAllRouter [hint] $

231 route (Proxy :: Proxy api)

232 route (Proxy :: Proxy api)

232 context

233 context

233 (addCapture d $ \ txts -> withRequest $ \ request ->

234 (addCapture d $ \ txts -> withRequest $ \ request ->

@@ -238,6 +239,7 @@ instance (KnownSymbol capture, FromHttpApiData a

238 where

239 where

239 rep = typeRep (Proxy :: Proxy CaptureAll)

240 rep = typeRep (Proxy :: Proxy CaptureAll)

240 formatError = urlParseErrorFormatter $ getContextEntry (mkContextWithErrorFormatter context)

241 formatError = urlParseErrorFormatter $ getContextEntry (mkContextWithErrorFormatter context)

242+ hint = CaptureHint (T.pack $ symbolVal $ Proxy @capture) (typeRep (Proxy :: Proxy [a]))

241

243

242allowedMethodHead :: Method -> Request -> Bool

244allowedMethodHead :: Method -> Request -> Bool

243allowedMethodHead method request = method == methodGet && requestMethod request == methodHead

245allowedMethodHead method request = method == methodGet && requestMethod request == methodHead

servant-server/src/Servant/Server/Internal/Router.hs+31−14

@@ -9,12 +9,16 @@ import Prelude.Compat

9

10import Data.Function

11 (on)

12+import Data.List

13+ (nub)

12import Data.Map

14import Data.Map

13 (Map)

15 (Map)

14import qualified Data.Map as M

16import qualified Data.Map as M

15import Data.Text

17import Data.Text

16 (Text)

18 (Text)

17import qualified Data.Text as T

19import qualified Data.Text as T

20+import Data.Typeable

21+ (TypeRep)

18import Network.Wai

22import Network.Wai

19 (Response, pathInfo)

23 (Response, pathInfo)

20import Servant.Server.Internal.ErrorFormatter

24import Servant.Server.Internal.ErrorFormatter

@@ -24,6 +28,18 @@ import Servant.Server.Internal.ServerError

24

28

25type Router env = Router' env RoutingApplication

29type Router env = Router' env RoutingApplication

26

30

31+data CaptureHint = CaptureHint

32+ { captureName :: Text

33+ , captureType :: TypeRep

34+ }

35+ deriving (Show, Eq)

36+

37+toCaptureTag :: CaptureHint -> Text

38+toCaptureTag hint = captureName hint <> "::" <> (T.pack . show) (captureType hint)

39+

40+toCaptureTags :: [CaptureHint] -> Text

41+toCaptureTags hints = "<" <> T.intercalate "|" (map toCaptureTag hints) <> ">"

42+

27-- | Internal representation of a router.

43-- | Internal representation of a router.

28--

44--

29-- The first argument describes an environment type that is

45-- The first argument describes an environment type that is

@@ -36,10 +52,10 @@ data Router' env a =

36 -- ^ the map contains routers for subpaths (first path component used

52 -- ^ the map contains routers for subpaths (first path component used

37 -- for lookup and removed afterwards), the list contains handlers

53 -- for lookup and removed afterwards), the list contains handlers

38 -- for the empty path, to be tried in order

54 -- for the empty path, to be tried in order

39− | CaptureRouter (Router' (Text, env) a)

55+ | CaptureRouter [CaptureHint] (Router' (Text, env) a)

40 -- ^ first path component is passed to the child router in its

56 -- ^ first path component is passed to the child router in its

41 -- environment and removed afterwards

57 -- environment and removed afterwards

42− | CaptureAllRouter (Router' ([Text], env) a)

58+ | CaptureAllRouter [CaptureHint] (Router' ([Text], env) a)

43 -- ^ all path components are passed to the child router in its

59 -- ^ all path components are passed to the child router in its

44 -- environment and are removed afterwards

60 -- environment and are removed afterwards

45 | RawRouter (env -> a)

61 | RawRouter (env -> a)

@@ -69,8 +85,8 @@ leafRouter l = StaticRouter M.empty [l]

69choice :: Router' env a -> Router' env a -> Router' env a

85choice :: Router' env a -> Router' env a -> Router' env a

70choice (StaticRouter table1 ls1) (StaticRouter table2 ls2) =

86choice (StaticRouter table1 ls1) (StaticRouter table2 ls2) =

71 StaticRouter (M.unionWith choice table1 table2) (ls1 ++ ls2)

87 StaticRouter (M.unionWith choice table1 table2) (ls1 ++ ls2)

72−choice (CaptureRouter router1) (CaptureRouter router2) =

88+choice (CaptureRouter hints1 router1) (CaptureRouter hints2 router2) =

73− CaptureRouter (choice router1 router2)

89+ CaptureRouter (nub $ hints1 ++ hints2) (choice router1 router2)

74choice router1 (Choice router2 router3) = Choice (choice router1 router2) router3

90choice router1 (Choice router2 router3) = Choice (choice router1 router2) router3

75choice router1 router2 = Choice router1 router2

91choice router1 router2 = Choice router1 router2

76

92

@@ -84,7 +100,7 @@ choice router1 router2 = Choice router1 router2

84--

100--

85data RouterStructure =

101data RouterStructure =

86 StaticRouterStructure (Map Text RouterStructure) Int

102 StaticRouterStructure (Map Text RouterStructure) Int

87− | CaptureRouterStructure RouterStructure

103+ | CaptureRouterStructure [CaptureHint] RouterStructure

88 | RawRouterStructure

104 | RawRouterStructure

89 | ChoiceStructure RouterStructure RouterStructure

105 | ChoiceStructure RouterStructure RouterStructure

90 deriving (Eq, Show)

106 deriving (Eq, Show)

@@ -98,11 +114,11 @@ data RouterStructure =

98routerStructure :: Router' env a -> RouterStructure

114routerStructure :: Router' env a -> RouterStructure

99routerStructure (StaticRouter m ls) =

115routerStructure (StaticRouter m ls) =

100 StaticRouterStructure (fmap routerStructure m) (length ls)

116 StaticRouterStructure (fmap routerStructure m) (length ls)

101−routerStructure (CaptureRouter router) =

117+routerStructure (CaptureRouter hints router) =

102− CaptureRouterStructure $

118+ CaptureRouterStructure hints $

103 routerStructure router

119 routerStructure router

104−routerStructure (CaptureAllRouter router) =

120+routerStructure (CaptureAllRouter hints router) =

105− CaptureRouterStructure $

121+ CaptureRouterStructure hints $

106 routerStructure router

122 routerStructure router

107routerStructure (RawRouter _) =

123routerStructure (RawRouter _) =

108 RawRouterStructure

124 RawRouterStructure

@@ -114,8 +130,8 @@ routerStructure (Choice r1 r2) =

114-- | Compare the structure of two routers.

130-- | Compare the structure of two routers.

115--

131--

116sameStructure :: Router' env a -> Router' env b -> Bool

132sameStructure :: Router' env a -> Router' env b -> Bool

117−sameStructure r1 r2 =

133+sameStructure router1 router2 =

118− routerStructure r1 == routerStructure r2

134+ routerStructure router1 == routerStructure router2

119

135

120-- | Provide a textual representation of the

136-- | Provide a textual representation of the

121-- structure of a router.

137-- structure of a router.

@@ -126,7 +142,8 @@ routerLayout router =

126 where

142 where

127 mkRouterLayout :: Bool -> RouterStructure -> [Text]

143 mkRouterLayout :: Bool -> RouterStructure -> [Text]

128 mkRouterLayout c (StaticRouterStructure m n) = mkSubTrees c (M.toList m) n

144 mkRouterLayout c (StaticRouterStructure m n) = mkSubTrees c (M.toList m) n

129− mkRouterLayout c (CaptureRouterStructure r) = mkSubTree c "<capture>" (mkRouterLayout False r)

145+ mkRouterLayout c (CaptureRouterStructure hints r) =

146+ mkSubTree c (toCaptureTags hints) (mkRouterLayout False r)

130 mkRouterLayout c RawRouterStructure =

147 mkRouterLayout c RawRouterStructure =

131 if c then ["├─ <raw>"] else ["└─ <raw>"]

148 if c then ["├─ <raw>"] else ["└─ <raw>"]

132 mkRouterLayout c (ChoiceStructure r1 r2) =

149 mkRouterLayout c (ChoiceStructure r1 r2) =

@@ -169,7 +186,7 @@ runRouterEnv fmt router env request respond =

169 -> let request' = request { pathInfo = rest }

186 -> let request' = request { pathInfo = rest }

170 in runRouterEnv fmt router' env request' respond

187 in runRouterEnv fmt router' env request' respond

171 _ -> respond $ Fail $ fmt request

188 _ -> respond $ Fail $ fmt request

172− CaptureRouter router' ->

189+ CaptureRouter _ router' ->

173 case pathInfo request of

190 case pathInfo request of

174 [] -> respond $ Fail $ fmt request

191 [] -> respond $ Fail $ fmt request

175 -- This case is to handle trailing slashes.

192 -- This case is to handle trailing slashes.

@@ -177,7 +194,7 @@ runRouterEnv fmt router env request respond =

177 first : rest

194 first : rest

178 -> let request' = request { pathInfo = rest }

195 -> let request' = request { pathInfo = rest }

179 in runRouterEnv fmt router' (first, env) request' respond

196 in runRouterEnv fmt router' (first, env) request' respond

180− CaptureAllRouter router' ->

197+ CaptureAllRouter _ router' ->

181 let segments = pathInfo request

198 let segments = pathInfo request

182 request' = request { pathInfo = [] }

199 request' = request { pathInfo = [] }

183 in runRouterEnv fmt router' (segments, env) request' respond

200 in runRouterEnv fmt router' (segments, env) request' respond

servant-server/test/Servant/Server/RouterSpec.hs+127−6

@@ -9,7 +9,9 @@ import Control.Monad

9import Data.Proxy

10 (Proxy (..))

11import Data.Text

12− (unpack)

12+ (Text, unpack)

13+import Data.Typeable

14+ (typeRep)

13import Network.HTTP.Types

15import Network.HTTP.Types

14 (Status (..))

16 (Status (..))

15import Network.Wai

17import Network.Wai

@@ -27,6 +29,7 @@ spec :: Spec

27spec = describe "Servant.Server.Internal.Router" $ do

29spec = describe "Servant.Server.Internal.Router" $ do

28 routerSpec

30 routerSpec

29 distributivitySpec

31 distributivitySpec

32+ serverLayoutSpec

30

33

31routerSpec :: Spec

34routerSpec :: Spec

32routerSpec = do

35routerSpec = do

@@ -51,7 +54,7 @@ routerSpec = do

51 toApp = toApplication . runRouter (const err404)

54 toApp = toApplication . runRouter (const err404)

52

55

53 cap :: Router ()

56 cap :: Router ()

54− cap = CaptureRouter $

57+ cap = CaptureRouter [hint] $

55 let delayed = addCapture (emptyDelayed $ Route pure) (const $ delayedFail err400)

58 let delayed = addCapture (emptyDelayed $ Route pure) (const $ delayedFail err400)

56 in leafRouter

59 in leafRouter

57 $ \env req res ->

60 $ \env req res ->

@@ -59,6 +62,9 @@ routerSpec = do

59 . const

62 . const

60 $ Route success

63 $ Route success

61

64

65+ hint :: CaptureHint

66+ hint = CaptureHint "anything" $ typeRep (Proxy :: Proxy ())

67+

62 router :: Router ()

68 router :: Router ()

63 router = leafRouter (\_ _ res -> res $ Route success)

69 router = leafRouter (\_ _ res -> res $ Route success)

64 `Choice` cap

70 `Choice` cap

@@ -98,12 +104,30 @@ distributivitySpec =

98 it "properly handles mixing static paths at different levels" $ do

104 it "properly handles mixing static paths at different levels" $ do

99 level `shouldHaveSameStructureAs` levelRef

105 level `shouldHaveSameStructureAs` levelRef

100

106

107+serverLayoutSpec :: Spec

108+serverLayoutSpec =

109+ describe "serverLayout" $ do

110+ it "correctly represents the example API" $ do

111+ exampleLayout `shouldHaveLayout` expectedExampleLayout

112+ it "aggregates capture hints when different" $ do

113+ captureDifferentTypes `shouldHaveLayout` expectedCaptureDifferentTypes

114+ it "nubs capture hints when equal" $ do

115+ captureSameType `shouldHaveLayout` expectedCaptureSameType

116+ it "properly displays CaptureAll hints" $ do

117+ captureAllLayout `shouldHaveLayout` expectedCaptureAllLayout

118+

101shouldHaveSameStructureAs ::

119shouldHaveSameStructureAs ::

102 (HasServer api1 '[], HasServer api2 '[]) => Proxy api1 -> Proxy api2 -> Expectation

120 (HasServer api1 '[], HasServer api2 '[]) => Proxy api1 -> Proxy api2 -> Expectation

103shouldHaveSameStructureAs p1 p2 =

121shouldHaveSameStructureAs p1 p2 =

104 unless (sameStructure (makeTrivialRouter p1) (makeTrivialRouter p2)) $

122 unless (sameStructure (makeTrivialRouter p1) (makeTrivialRouter p2)) $

105 expectationFailure ("expected:\n" ++ unpack (layout p2) ++ "\nbut got:\n" ++ unpack (layout p1))

123 expectationFailure ("expected:\n" ++ unpack (layout p2) ++ "\nbut got:\n" ++ unpack (layout p1))

106

124

125+shouldHaveLayout ::

126+ (HasServer api '[]) => Proxy api -> Text -> Expectation

127+shouldHaveLayout p l =

128+ unless (routerLayout (makeTrivialRouter p) == l) $

129+ expectationFailure ("expected:\n" ++ unpack l ++ "\nbut got:\n" ++ unpack (layout p))

130+

107makeTrivialRouter :: (HasServer layout '[]) => Proxy layout -> Router ()

131makeTrivialRouter :: (HasServer layout '[]) => Proxy layout -> Router ()

108makeTrivialRouter p =

132makeTrivialRouter p =

109 route p EmptyContext (emptyDelayed (FailFatal err501))

133 route p EmptyContext (emptyDelayed (FailFatal err501))

@@ -144,12 +168,12 @@ staticRef = Proxy

144-- structure:

168-- structure:

145

169

146type Dynamic =

170type Dynamic =

147− "a" :> Capture "foo" Int :> "b" :> End

171+ "a" :> Capture "foo" Int :> "b" :> End

148− :<|> "a" :> Capture "bar" Bool :> "c" :> End

172+ :<|> "a" :> Capture "foo" Int :> "c" :> End

149− :<|> "a" :> Capture "baz" Char :> "d" :> End

173+ :<|> "a" :> Capture "foo" Int :> "d" :> End

150

174

151type DynamicRef =

175type DynamicRef =

152− "a" :> Capture "anything" () :>

176+ "a" :> Capture "foo" Int :>

153 ("b" :> End :<|> "c" :> End :<|> "d" :> End)

177 ("b" :> End :<|> "c" :> End :<|> "d" :> End)

154

178

155dynamic :: Proxy Dynamic

179dynamic :: Proxy Dynamic

@@ -339,3 +363,100 @@ level = Proxy

339

363

340levelRef :: Proxy LevelRef

364levelRef :: Proxy LevelRef

341levelRef = Proxy

365levelRef = Proxy

366+

367+-- The example API for the 'layout' function.

368+-- Should get factorized by the 'choice' smart constructor.

369+type ExampleLayout =

370+ "a" :> "d" :> Get '[JSON] NoContent

371+ :<|> "b" :> Capture "x" Int :> Get '[JSON] Bool

372+ :<|> "c" :> Put '[JSON] Bool

373+ :<|> "a" :> "e" :> Get '[JSON] Int

374+ :<|> "b" :> Capture "x" Int :> Put '[JSON] Bool

375+ :<|> Raw

376+

377+exampleLayout :: Proxy ExampleLayout

378+exampleLayout = Proxy

379+

380+-- The expected representation of the example API layout

381+--

382+expectedExampleLayout :: Text

383+expectedExampleLayout =

384+ "/\n\

385+ \├─ a/\n\

386+ \│ ├─ d/\n\

387+ \│ │ └─•\n\

388+ \│ └─ e/\n\

389+ \│ └─•\n\

390+ \├─ b/\n\

391+ \│ └─ <x::Int>/\n\

392+ \│ ├─•\n\

393+ \│ ┆\n\

394+ \│ └─•\n\

395+ \├─ c/\n\

396+ \│ └─•\n\

397+ \┆\n\

398+ \└─ <raw>\n"

399+

400+-- A capture API with all capture types being the same

401+--

402+type CaptureSameType =

403+ "a" :> Capture "foo" Int :> "b" :> End

404+ :<|> "a" :> Capture "foo" Int :> "c" :> End

405+ :<|> "a" :> Capture "foo" Int :> "d" :> End

406+

407+captureSameType :: Proxy CaptureSameType

408+captureSameType = Proxy

409+

410+-- The expected representation of the CaptureSameType API layout.

411+--

412+expectedCaptureSameType :: Text

413+expectedCaptureSameType =

414+ "/\n\

415+ \└─ a/\n\

416+ \ └─ <foo::Int>/\n\

417+ \ ├─ b/\n\

418+ \ │ └─•\n\

419+ \ ├─ c/\n\

420+ \ │ └─•\n\

421+ \ └─ d/\n\

422+ \ └─•\n"

423+

424+-- A capture API capturing different types

425+--

426+type CaptureDifferentTypes =

427+ "a" :> Capture "foo" Int :> "b" :> End

428+ :<|> "a" :> Capture "bar" Bool :> "c" :> End

429+ :<|> "a" :> Capture "baz" Char :> "d" :> End

430+

431+captureDifferentTypes :: Proxy CaptureDifferentTypes

432+captureDifferentTypes = Proxy

433+

434+-- The expected representation of the CaptureDifferentTypes API layout.

435+--

436+expectedCaptureDifferentTypes :: Text

437+expectedCaptureDifferentTypes =

438+ "/\n\

439+ \└─ a/\n\

440+ \ └─ <foo::Int|bar::Bool|baz::Char>/\n\

441+ \ ├─ b/\n\

442+ \ │ └─•\n\

443+ \ ├─ c/\n\

444+ \ │ └─•\n\

445+ \ └─ d/\n\

446+ \ └─•\n"

447+

448+-- An API with a CaptureAll part

449+

450+type CaptureAllLayout = "a" :> CaptureAll "foos" Int :> End

451+

452+captureAllLayout :: Proxy CaptureAllLayout

453+captureAllLayout = Proxy

454+

455+-- The expected representation of the CaptureAllLayout API.

456+--

457+expectedCaptureAllLayout :: Text

458+expectedCaptureAllLayout =

459+ "/\n\

460+ \└─ a/\n\

461+ \ └─ <foos::[Int]>/\n\

462+ \ └─•\n"

servant-swagger/servant-swagger.cabal+4−4

@@ -77,7 +77,7 @@ library

77 , http-media >=0.7.1.3 && <0.9

78 , insert-ordered-containers >=0.2.1.0 && <0.3

79 , lens >=4.17 && <6

80− , servant >=0.18.1 && <0.20

80+ , servant >=0.18.2 && <0.20

81 , singleton-bool >=0.1.4 && <0.2

82 , swagger2 >=2.3.0.1 && <3

83 , text >=1.2.3.0 && <2.1

@@ -106,14 +106,14 @@ test-suite spec

106 type: exitcode-stdio-1.0

107 hs-source-dirs: test

108 main-is: Spec.hs

109− build-tool-depends: hspec-discover:hspec-discover >=2.6.0 && <2.8

109+ build-tool-depends: hspec-discover:hspec-discover >=2.6.0 && <2.10

110 build-depends: base

111 , base-compat

112 , aeson >=1.4.2.0 && <3

113− , hspec >=2.6.0 && <2.8

113+ , hspec >=2.6.0 && <2.10

114 , QuickCheck

115 , lens

116− , lens-aeson >=1.0.2 && <1.2

116+ , lens-aeson >=1.0.2 && <1.3

117 , servant

118 , servant-swagger

119 , swagger2

servant-swagger/src/Servant/Swagger.hs+5−3

@@ -55,6 +55,7 @@ import Servant.Swagger.Internal.Orphans ()

55-- >>> import Data.Typeable

56-- >>> import GHC.Generics

57-- >>> import Servant.API

58+-- >>> import System.Environment

58-- >>> import Test.Hspec

59-- >>> import Test.Hspec

59-- >>> import Test.QuickCheck

60-- >>> import Test.QuickCheck

60-- >>> import qualified Data.ByteString.Lazy.Char8 as BSL8

61-- >>> import qualified Data.ByteString.Lazy.Char8 as BSL8

@@ -64,6 +65,7 @@ import Servant.Swagger.Internal.Orphans ()

64-- >>> :set -XGeneralizedNewtypeDeriving

65-- >>> :set -XGeneralizedNewtypeDeriving

65-- >>> :set -XOverloadedStrings

66-- >>> :set -XOverloadedStrings

66-- >>> :set -XTypeOperators

67-- >>> :set -XTypeOperators

68+-- >>> setEnv "HSPEC_COLOR" "no"

67-- >>> data User = User { name :: String, age :: Int } deriving (Show, Generic, Typeable)

69-- >>> data User = User { name :: String, age :: Int } deriving (Show, Generic, Typeable)

68-- >>> newtype UserId = UserId Integer deriving (Show, Generic, Typeable, ToJSON)

70-- >>> newtype UserId = UserId Integer deriving (Show, Generic, Typeable, ToJSON)

69-- >>> instance ToJSON User

71-- >>> instance ToJSON User

@@ -160,11 +162,11 @@ import Servant.Swagger.Internal.Orphans ()

160-- >>> instance Arbitrary UserId where arbitrary = UserId <$> arbitrary

162-- >>> instance Arbitrary UserId where arbitrary = UserId <$> arbitrary

161-- >>> hspec $ validateEveryToJSON (Proxy :: Proxy UserAPI)

163-- >>> hspec $ validateEveryToJSON (Proxy :: Proxy UserAPI)

162-- <BLANKLINE>

164-- <BLANKLINE>

163−-- [User]

165+-- [User]...

164-- ...

166-- ...

165−-- User

167+-- User...

166-- ...

168-- ...

167−-- UserId

169+-- UserId...

168-- ...

170-- ...

169-- Finished in ... seconds

171-- Finished in ... seconds

170-- 3 examples, 0 failures

172-- 3 examples, 0 failures

servant-swagger/src/Servant/Swagger/Internal.hs+11

@@ -3,11 +3,13 @@

3{-# LANGUAGE DataKinds #-}

4{-# LANGUAGE FlexibleContexts #-}

5{-# LANGUAGE FlexibleInstances #-}

6+{-# LANGUAGE OverloadedLists #-}

6{-# LANGUAGE OverloadedStrings #-}

7{-# LANGUAGE OverloadedStrings #-}

7{-# LANGUAGE PolyKinds #-}

8{-# LANGUAGE PolyKinds #-}

8{-# LANGUAGE RankNTypes #-}

9{-# LANGUAGE RankNTypes #-}

9{-# LANGUAGE ScopedTypeVariables #-}

10{-# LANGUAGE ScopedTypeVariables #-}

10{-# LANGUAGE TypeOperators #-}

11{-# LANGUAGE TypeOperators #-}

12+{-# LANGUAGE TypeFamilies #-}

11#if __GLASGOW_HASKELL__ >= 806

13#if __GLASGOW_HASKELL__ >= 806

12{-# LANGUAGE UndecidableInstances #-}

14{-# LANGUAGE UndecidableInstances #-}

13#endif

15#endif

@@ -30,11 +32,13 @@ import qualified Data.Swagger as Swagger

30import Data.Swagger.Declare

32import Data.Swagger.Declare

31import Data.Text (Text)

33import Data.Text (Text)

32import qualified Data.Text as Text

34import qualified Data.Text as Text

35+import GHC.Generics (D1, Meta(..), Rep)

33import GHC.TypeLits

36import GHC.TypeLits

34import Network.HTTP.Media (MediaType)

37import Network.HTTP.Media (MediaType)

35import Servant.API

38import Servant.API

36import Servant.API.Description (FoldDescription,

39import Servant.API.Description (FoldDescription,

37 reflectDescription)

40 reflectDescription)

41+import Servant.API.Generic (ToServantApi, AsApi)

38import Servant.API.Modifiers (FoldRequired)

42import Servant.API.Modifiers (FoldRequired)

39

43

40import Servant.Swagger.Internal.TypeLevel.API

44import Servant.Swagger.Internal.TypeLevel.API

@@ -149,6 +153,10 @@ mkEndpointNoContentVerb path _ = mempty

149addParam :: Param -> Swagger -> Swagger

153addParam :: Param -> Swagger -> Swagger

150addParam param = allOperations.parameters %~ (Inline param :)

154addParam param = allOperations.parameters %~ (Inline param :)

151

155

156+-- | Add a tag to every operation in the spec.

157+addTag :: Text -> Swagger -> Swagger

158+addTag tag = allOperations.tags %~ ([tag] <>)

159+

152-- | Add accepted content types to every operation in the spec.

160-- | Add accepted content types to every operation in the spec.

153addConsumes :: [MediaType] -> Swagger -> Swagger

161addConsumes :: [MediaType] -> Swagger -> Swagger

154addConsumes cs = allOperations.consumes %~ (<> Just (MimeList cs))

162addConsumes cs = allOperations.consumes %~ (<> Just (MimeList cs))

@@ -439,6 +447,9 @@ instance (ToSchema a, Accept ct, HasSwagger sub, KnownSymbol (FoldDescription mo

439 & required ?~ True

447 & required ?~ True

440 & schema .~ ParamBody ref

448 & schema .~ ParamBody ref

441

449

450+instance (HasSwagger (ToServantApi routes), KnownSymbol datatypeName, Rep (routes AsApi) ~ D1 ('MetaData datatypeName moduleName packageName isNewtype) f) => HasSwagger (NamedRoutes routes) where

451+ toSwagger _ = addTag (Text.pack $ symbolVal (Proxy :: Proxy datatypeName)) (toSwagger (Proxy :: Proxy (ToServantApi routes)))

452+

442-- =======================================================================

453-- =======================================================================

443-- Below are the definitions that should be in Servant.API.ContentTypes

454-- Below are the definitions that should be in Servant.API.ContentTypes

444-- =======================================================================

455-- =======================================================================

servant-swagger/src/Servant/Swagger/Internal/Test.hs+8−6

@@ -29,10 +29,12 @@ import Servant.Swagger.Internal.TypeLevel

29-- >>> import Control.Applicative

30-- >>> import GHC.Generics

31-- >>> import Test.QuickCheck

32+-- >>> import System.Environment (setEnv)

32-- >>> :set -XDeriveGeneric

33-- >>> :set -XDeriveGeneric

33-- >>> :set -XGeneralizedNewtypeDeriving

34-- >>> :set -XGeneralizedNewtypeDeriving

34-- >>> :set -XDataKinds

35-- >>> :set -XDataKinds

35-- >>> :set -XTypeOperators

36-- >>> :set -XTypeOperators

37+-- >>> setEnv "HSPEC_COLOR" "no"

36

38

37-- | Verify that every type used with @'JSON'@ content type in a servant API

39-- | Verify that every type used with @'JSON'@ content type in a servant API

38-- has compatible @'ToJSON'@ and @'ToSchema'@ instances using @'validateToJSON'@.

40-- has compatible @'ToJSON'@ and @'ToSchema'@ instances using @'validateToJSON'@.

@@ -53,10 +55,10 @@ import Servant.Swagger.Internal.TypeLevel

53--

55--

54-- >>> hspec $ context "ToJSON matches ToSchema" $ validateEveryToJSON (Proxy :: Proxy UserAPI)

56-- >>> hspec $ context "ToJSON matches ToSchema" $ validateEveryToJSON (Proxy :: Proxy UserAPI)

55-- <BLANKLINE>

57-- <BLANKLINE>

56−-- ToJSON matches ToSchema

58+-- ToJSON matches ToSchema...

57−-- User

59+-- User...

58-- ...

60-- ...

59−-- UserId

61+-- UserId...

60-- ...

62-- ...

61-- Finished in ... seconds

63-- Finished in ... seconds

62-- 2 examples, 0 failures

64-- 2 examples, 0 failures

@@ -118,11 +120,11 @@ validateEveryToJSONWithPatternChecker checker _ = props

118-- :}

120-- :}

119-- <BLANKLINE>

121-- <BLANKLINE>

120-- read . show == id

122-- read . show == id

121−-- Bool

123+-- Bool...

122-- ...

124-- ...

123−-- Int

125+-- Int...

124-- ...

126-- ...

125−-- [Char]

127+-- [Char]...

126-- ...

128-- ...

127-- Finished in ... seconds

129-- Finished in ... seconds

128-- 3 examples, 0 failures

130-- 3 examples, 0 failures

servant/servant.cabal+2−2

@@ -166,9 +166,9 @@ test-suite spec

166

167 -- Additional dependencies

168 build-depends:

169− hspec >= 2.6.0 && < 2.9

169+ hspec >= 2.6.0 && < 2.10

170 , QuickCheck >= 2.12.6.1 && < 2.15

171 , quickcheck-instances >= 0.3.19 && < 0.4

172

173 build-tool-depends:

174− hspec-discover:hspec-discover >= 2.6.0 && < 2.9

174+ hspec-discover:hspec-discover >= 2.6.0 && < 2.10

servant/src/Servant/API/ContentTypes.hs+1−1

@@ -295,7 +295,7 @@ instance {-# OVERLAPPABLE #-}

295-- then this would be taken care of. However there is no more specific instance

296-- between that and 'MimeRender JSON a', so we do this instead

297instance {-# OVERLAPPING #-} ( Accept ctyp ) => AllMimeRender '[ctyp] NoContent where

298− allMimeRender _ _ = map (, "") $ NE.toList $ contentTypes pctyp

298+ allMimeRender _ NoContent = map (, "") $ NE.toList $ contentTypes pctyp

299 where

300 pctyp = Proxy :: Proxy ctyp

301

servant/test/Servant/API/ContentTypesSpec.hs+11

@@ -33,6 +33,8 @@ import Data.String.Conversions

33import qualified Data.Text as TextS

34import qualified Data.Text.Encoding as TextSE

35import qualified Data.Text.Lazy as TextL

36+import Control.Exception

37+ (evaluate)

36import GHC.Generics

38import GHC.Generics

37import Test.Hspec

39import Test.Hspec

38import Test.QuickCheck

40import Test.QuickCheck

@@ -78,6 +80,15 @@ spec = describe "Servant.API.ContentTypes" $ do

78 it "has mimeUnrender reverse mimeRender for valid top-level json " $ do

80 it "has mimeUnrender reverse mimeRender for valid top-level json " $ do

79 property $ \x -> mimeUnrender p (mimeRender p x) == Right (x::SomeData)

81 property $ \x -> mimeUnrender p (mimeRender p x) == Right (x::SomeData)

80

82

83+ describe "The NoContent Content-Type type" $ do

84+ let p = Proxy :: Proxy '[JSON]

85+

86+ it "does not render any content" $

87+ allMimeRender p NoContent `shouldSatisfy` (all (BSL8.null . snd))

88+

89+ it "evaluates the NoContent value" $

90+ evaluate (allMimeRender p (undefined :: NoContent)) `shouldThrow` anyErrorCall

91+

81 describe "The PlainText Content-Type type" $ do

92 describe "The PlainText Content-Type type" $ do

82 let p = Proxy :: Proxy PlainText

93 let p = Proxy :: Proxy PlainText

83

94