servant-client-core
Core functionality and class for client function generation for servant APIs
Version on this page: | 0.20@rev:3 |
LTS Haskell 22.33: | 0.20@rev:4 |
Stackage Nightly 2024-09-07: | 0.20.2 |
Latest on Hackage: | 0.20.2 |
servant-client-core-0.20@sha256:fb4d8c3ee3bcb09afbea93994cc9d0d54278d5460213b8002c36b08deb76070b,3817
Module documentation for 0.20
- Servant
- Servant.Client
servant-client-core
HTTP-client-agnostic client functions for servant APIs.
This library should mainly be of interest to backend- and combinator-writers.
For backend-writers
If you are creating a new backend, you’ll need to:
- Define a
RunClient
instance for your datatype (call itMyMonad
) - Define a
ClientLike
instance. This will look like:
instance ClientLike (MyMonad a) (MyMonad a) where
mkClient = id
- Re-export the module Servant.Client.Core.Reexport so that your end-users can be blissfully unaware of ‘servant-client-core’, and so each backend-package comes closer to the warm hearth of the drop-in-replacement equivalence class.
For combinator-writers
You’ll need to define a new HasClient
instance for your combinator. There are
plenty of examples to guide you in the
HasClient module.
Changes
The latest version of this document is on GitHub.
Changelog for servant
package contains significant entries for all core packages.
Package versions follow the Package Versioning Policy: in A.B.C, bumps to either A or B represent major versions.
0.20
-
Escape special chars in QueryParams. #1584 #1597
Escape special chars in QueryParam (
:@&=+$
) in servant-client. Note that this mean binary data will not work as is, and so reverts the functionality in #1432. -
Handle Cookies correctly for RunStreamingClient #1605 #1606
Makes
performWithStreamingRequest
take into consideration the CookieJar, which it previously didn’t. -
Fix the handling of multiple headers with the same name. #1666
servant-client no longer concatenates the values of response headers with the same name. This fixes an issue with parsing multiple
Set-Cookie
headers.
0.19
Significant changes
- Drop support for GHC < 8.6.
- Support GHC 9.0 (GHC 9.2 should work as well, but isn’t fully tested yet).
- Support Aeson 2 (#1475), which fixes a DOS vulnerability related to hash collisions.
- Add
NamedRoutes
combinator, making support for records first-class in Servant (#1388). - Add custom type errors for partially applied combinators (#1289, #1486).
- servant-client / servant-client-core / servant-http-streams: Fix erroneous behavior, where only 2XX status codes would be considered successful, irrelevant of the status parameter specified by the verb combinator. (#1469)
- servant-client / servant-client-core: Fix
Show
instance forServant.Client.Core.Request
. - servant-client / servant-client-core: Allow passing arbitrary binary data in Query parameters. (#1432).
Other changes
- Various version bumps.
0.18.3
Significant changes
- Add response header support to UVerb (#1420)
Other changes
- Support GHC-9.0.1.
- Bump
bytestring
,hspec
,base64-bytestring
andQuickCheck
dependencies.
0.18.2
Significant changes
- Support
Fragment
combinator.
0.18.1
Significant changes
- Union verbs
Other changes
- Bump “tested-with” ghc versions
- Loosen bound on base16-bytestring
0.18
Significant changes
- Support for ghc8.8 (#1318, #1326, #1327)
0.17
Significant changes
-
Add NoContentVerb #1028 #1219 #1228
The
NoContent
API endpoints should now useNoContentVerb
combinator. The API type changes are usually of the kind- :<|> PostNoContent '[JSON] NoContent + :<|> PostNoContent
i.e. one doesn’t need to specify the content-type anymore. There is no content.
-
Capture
can beLenient
#1155 #1156You can specify a lenient capture as
:<|> "capture-lenient" :> Capture' '[Lenient] "foo" Int :> GET
which will make the capture always succeed. Handlers will be of the type
Either String CapturedType
, whereLeft err
represents the possible parse failure.
Other changes
-
servant-client servant-client-core servant-http-streams Fix Verb with headers checking content type differently #1200 #1204
For
Verb
s with responseHeaders
, the implementation didn’t check for the content-type of the response. Now it does. -
servant-client servant-http-streams
HasClient
instance forStream
withHeaders
#1170 #1197 -
servant-client Redact the authorization header in Show and exceptions #1238
0.16
-
Rename
ServantError
toClientError
,ServantErr
toServerError
#1131 -
servant-client-core Rearrange modules. No more
Internal
modules, whole API is versioned. #1130 -
servant-client-core
RequestBody
is now= RequestBodyLBS LBS.ByteString | RequestBodyBS BS.ByteString | RequestBodySource (SourceIO LBS.ByteString)
i.e. no more replicates
http-client
s API. #1117 -
servant-client-core Keep structured exceptions in
ConnectionError
constructor ofClientError
#1115-| ConnectionError Text +| ConnectionError SomeException
-
servant-client-core Preserve failing request in
FailureResponse
constructor ofClientError
#1114-FailureResponse Response +-- | The server returned an error response including the +-- failing request. 'requestPath' includes the 'BaseUrl' and the +-- path of the request. +FailureResponse (RequestF () (BaseUrl, BS.ByteString)) Response
-
servant-client Fix (implement)
StreamBody
instance #1110 -
servant-client Update CookieJar with intermediate request/responses (redirects) #1104
0.15
-
Streaming refactoring. #991 #1076 #1077
The streaming functionality (
Servant.API.Stream
) is refactored to useservant
’s ownSourceIO
type (seeServant.Types.SourceT
documentation), which replaces bothStreamGenerator
andResultStream
types.New conversion type-classes are
ToSourceIO
andFromSourceIO
(replacingToStreamGenerator
andBuildFromStream
). There are instances for conduit, pipes and machines in new packages: servant-conduit servant-pipes and servant-machines respectively.Writing new framing strategies is simpler. Check existing strategies for examples.
This change shouldn’t affect you, if you don’t use streaming endpoints.
-
servant-client Separate streaming client. #1066
We now have two
http-client
based clients, inServant.Client
andServant.Client.Streaming
.Their API is the same, except for
Servant.Client
cannot requestStream
endpoints.Servant.Client
is run by directrunClientM :: ClientM a -> ClientEnv -> IO (Either ServantError a)
Servant.Client.Streaming
can requestStream
endpoints.Servant.Client.Streaming
is used by CPSisedwithClientM :: ClientM a -> ClientEnv -> (Either ServantError a -> IO b) -> IO b
To access
Stream
endpoints useServant.Client.Streaming
withwithClientM
; otherwise you can continue usingServant.Client
withrunClientM
. You can use both too,ClientEnv
andBaseUrl
types are same for both.Note:
Servant.Client.Streaming
doesn’t stream non-Stream
endpoints. Requesting ordinaryVerb
endpoints (e.g.Get
) will block until the whole response is received.There is
Servant.Client.Streaming.runClientM
function, but it has restricted type.NFData a
constraint prevents using it withSourceT
,Conduit
etc. response types.runClientM :: NFData a => ClientM a -> ClientEnv -> IO (Either ServantError a)
This change shouldn’t affect you, if you don’t use streaming endpoints.
-
servant-client-core Related to the previous:
streamingResponse
is removed fromRunClient
. We have a new type-class:class RunClient m => RunStreamingClient m where withStreamingRequest :: Request -> (StreamingResponse -> IO a) -> m a
-
servant-client-core Add
NFData (GenResponse a)
andNFData ServantError
instances. #1076 -
servant-client-core Add
aeson
andLift BaseUrl
instances #1037
0.14.1
- Merge in
servant-generic
(by Patrick Chilton) intoservant
(Servant.API.Generic
),servant-client-code
(Servant.Client.Generic
) andservant-server
(Servant.Server.Generic
).
0.14
-
Stream
takes a status code argument-Stream method framing ctype a +Stream method status framing ctype a
-
ToStreamGenerator
definition changed, so it’s possible to write an instance for conduits.-class ToStreamGenerator f a where - toStreamGenerator :: f a -> StreamGenerator a +class ToStreamGenerator a b | a -> b where + toStreamGenerator :: a -> StreamGenerator b
(#959)
-
Added
NoFraming
streaming strategy (#959) -
servant-client-core Free
Client
implementation. Useful for testingHasClient
instances. (#920) -
servant-client-core Add
hoistClient
toHasClient
. Just likehoistServer
allows us to change the monad in which request handlers of a web application live, we also havehoistClient
for changing the monad in which client functions live. Read tutorial section for more information. (#936)iF you have own combinators, you’ll need to define a new method of
HasClient
class, for example:type Client m (MyCombinator :> api) = MyValue :> Client m api hoistClientMonad pm _ nt cl = hoistClientMonad pm (Proxy :: Proxy api) nt . cl
0.13.0.1
- Support
base-compat-0.10
0.13
0.12
- First version. Factored out of
servant-client
all the functionality that was independent of thehttp-client
backend.