@@ -1,17 +1,10 @@
1−{-# LANGUAGE BangPatterns #-}
2{-# LANGUAGE DataKinds #-}
1{-# LANGUAGE DataKinds #-}
3−{-# LANGUAGE DeriveDataTypeable #-}
4−{-# LANGUAGE DeriveGeneric #-}
5−{-# LANGUAGE FlexibleInstances #-}
6−{-# LANGUAGE GeneralizedNewtypeDeriving #-}
7−{-# LANGUAGE KindSignatures #-}
8{-# LANGUAGE LambdaCase #-}
2{-# LANGUAGE LambdaCase #-}
9−{-# LANGUAGE MultiParamTypeClasses #-}
10{-# LANGUAGE OverloadedStrings #-}
3{-# LANGUAGE OverloadedStrings #-}
11{-# LANGUAGE QuasiQuotes #-}
4{-# LANGUAGE QuasiQuotes #-}
12−{-# LANGUAGE RankNTypes #-}
13{-# LANGUAGE RecordWildCards #-}
5{-# LANGUAGE RecordWildCards #-}
14−{-# LANGUAGE ScopedTypeVariables #-}
6+{-# LANGUAGE RoleAnnotations #-}
7+{-# LANGUAGE TemplateHaskellQuotes #-}
15{-# LANGUAGE TypeFamilies #-}
8{-# LANGUAGE TypeFamilies #-}
16{-# LANGUAGE UndecidableInstances #-}
9{-# LANGUAGE UndecidableInstances #-}
@@ -26,61 +19,40 @@
27-- The documentation below is structured in such a way that the most
20-- The documentation below is structured in such a way that the most
28-- important information is presented first: you learn how to do HTTP
21-- important information is presented first: you learn how to do HTTP
29−-- requests, how to embed them in any monad you have, and then it gives you
22+-- requests, how to embed them in the monad you have, and then it gives you
30-- details about less-common things you may want to know about. The
23-- details about less-common things you may want to know about. The
31-- documentation is written with sufficient coverage of details and
24-- documentation is written with sufficient coverage of details and
32-- examples, and it's designed to be a complete tutorial on its own.
25-- examples, and it's designed to be a complete tutorial on its own.
34−-- /(A modest intro goes here, click on 'req' to start making requests.)/
36-- === About the library
27-- === About the library
38−-- Req is an easy-to-use, type-safe, expandable, high-level HTTP client
29+-- Req is an HTTP client library that attempts to be easy-to-use, type-safe,
39−-- library that just works without any fooling around.
30+-- and expandable.
41−-- What does the phrase “easy-to-use” mean? It means that the library is
32+-- “Easy-to-use” means that the library is designed to be beginner-friendly
42−-- designed to be beginner-friendly so it's simple to add to your monad
33+-- so it's simple to add to your monad stack, intuitive to work with,
43−-- stack, intuitive to work with, well-documented, and does not get in your
34+-- well-documented, and does not get in your way. Doing HTTP requests is a
44−-- way. Doing HTTP requests is a common task and Haskell library for this
35+-- common task and a Haskell library for this should be approachable and
45−-- should be very approachable and clear to beginners, thus certain
46−-- compromises were made. For example, one cannot currently modify
36+-- clear to beginners, thus certain compromises were made. For example, one
47−-- 'L.ManagerSettings' of the default manager because the library always
37+-- cannot currently modify 'L.ManagerSettings' of the default manager
48−-- uses the same implicit global manager for simplicity and maximal
38+-- because the library always uses the same implicit global manager for
49−-- connection sharing. There is a way to use your own manager with different
39+-- simplicity and maximal connection sharing. There is a way to use your own
50−-- settings, but it requires a bit more typing.
40+-- manager with different settings, but it requires more typing.
52−-- “Type-safe” means that the library is protective and eliminates certain
42+-- “Type-safe” means that the library tries to eliminate certain classes of
53−-- classes of errors. For example, we have correct-by-construction 'Url's,
43+-- errors. For example, we have correct-by-construction URLs; it is
54−-- it's guaranteed that the user does not send the request body when using
44+-- guaranteed that the user does not send the request body when using
55−-- methods like 'GET' or 'OPTIONS', and the amount of implicit assumptions
45+-- methods like GET or OPTIONS, and the amount of implicit assumptions is
56−-- is minimized by making the user specify his\/her intentions in an
46+-- minimized by making the user specify their intentions in an explicit
57−-- explicit form (for example, it's not possible to avoid specifying the
47+-- form. For example, it's not possible to avoid specifying the body or the
58−-- body or method of request). Authentication methods that assume HTTPS
48+-- method of a request. Authentication methods that assume HTTPS force the
59−-- force the user to use HTTPS at the type level. The library also carefully
49+-- user to use HTTPS at the type level.
60−-- hides underlying types from the lower-level @http-client@ package because
61−-- those types are not safe enough (for example 'L.Request' is an instance
62−-- of 'Data.String.IsString' and, if it's malformed, it will blow up at
65−-- “Expandable” refers to the ability of the library to be expanded without
51+-- “Expandable” refers to the ability to create new components without
66−-- having to resort to ugly hacking. For example, it's possible to define
52+-- having to resort to hacking. For example, it's possible to define your
67−-- your own HTTP methods, create new ways to construct the body of a
53+-- own HTTP methods, create new ways to construct the body of a request,
68−-- request, create new authorization options, perform a request in a
54+-- create new authorization options, perform a request in a different way,
69−-- different way, and create your own methods to parse and represent a
55+-- and create your own methods to parse a response.
70−-- response. As the user extends the library to satisfy his\/her special
71−-- needs, the new solutions will work just like the built-ins. However, all
72−-- of the common cases are also covered by the library out-of-the-box.
74−-- “High-level” means that there are less details to worry about. The
75−-- library is a result of my experiences as a Haskell consultant. Working
76−-- for several clients, who had very different projects, showed me that the
77−-- library should adapt easily to any particular style of writing Haskell
78−-- applications. For example, some people prefer throwing exceptions, while
79−-- others are concerned with purity. Just define 'handleHttpException'
80−-- accordingly when making your monad instance of 'MonadHttp' and it will
81−-- play together seamlessly. Finally, the library cuts down boilerplate
82−-- considerably, and helps you write concise, easy to read, and maintainable
85-- === Using with other libraries
57-- === Using with other libraries
@@ -109,6 +81,7 @@ module Network.HTTP.Req
109 -- $making-a-request
81 -- $making-a-request
113 withReqManager,
86 withReqManager,
@@ -145,6 +118,8 @@ module Network.HTTP.Req
145 useHttpURI,
118 useHttpURI,
146 useHttpsURI,
119 useHttpsURI,
149 -- ** Body
124 -- ** Body
@@ -169,11 +144,13 @@ module Network.HTTP.Req
169 -- $query-parameters
144 -- $query-parameters
171 queryFlag,
146 queryFlag,
172 QueryParam (..),
148 QueryParam (..),
174 -- *** Headers
150 -- *** Headers
176 attachHeader,
152 attachHeader,
178 -- *** Cookies
155 -- *** Cookies
179 -- $cookies
156 -- $cookies
@@ -220,52 +197,78 @@ module Network.HTTP.Req
221 -- * Other
198 -- * Other
222 HttpException (..),
199 HttpException (..),
200+ isStatusCodeException,
223 CanHaveBody (..),
201 CanHaveBody (..),
224 Scheme (..),
202 Scheme (..),
228−import qualified Blaze.ByteString.Builder as BB
206+import Blaze.ByteString.Builder qualified as BB
229import Control.Applicative
207import Control.Applicative
230import Control.Arrow (first, second)
208import Control.Arrow (first, second)
231−import Control.Exception hiding (TypeError)
209+import Control.Exception hiding (Handler (..), TypeError)
210+import Control.Monad (guard, void, (>=>))
232import Control.Monad.Base
211import Control.Monad.Base
212+import Control.Monad.Catch (Handler (..), MonadCatch, MonadMask, MonadThrow)
233import Control.Monad.IO.Class
213import Control.Monad.IO.Class
234−import Control.Monad.Reader
214+import Control.Monad.IO.Unlift
215+import Control.Monad.Reader (ReaderT (ReaderT), ask, lift, runReaderT)
216+import Control.Monad.Trans.Accum (AccumT)
217+import Control.Monad.Trans.Cont (ContT)
235import Control.Monad.Trans.Control
218import Control.Monad.Trans.Control
219+import Control.Monad.Trans.Except (ExceptT)
220+import Control.Monad.Trans.Identity (IdentityT)
221+import Control.Monad.Trans.Maybe (MaybeT)
222+import Control.Monad.Trans.RWS.CPS qualified as RWS.CPS
223+import Control.Monad.Trans.RWS.Lazy qualified as RWS.Lazy
224+import Control.Monad.Trans.RWS.Strict qualified as RWS.Strict
225+import Control.Monad.Trans.Select (SelectT)
226+import Control.Monad.Trans.State.Lazy qualified as State.Lazy
227+import Control.Monad.Trans.State.Strict qualified as State.Strict
228+import Control.Monad.Trans.Writer.CPS qualified as Writer.CPS
229+import Control.Monad.Trans.Writer.Lazy qualified as Writer.Lazy
230+import Control.Monad.Trans.Writer.Strict qualified as Writer.Strict
236import Control.Retry
231import Control.Retry
237import Data.Aeson (FromJSON (..), ToJSON (..))
232import Data.Aeson (FromJSON (..), ToJSON (..))
238−import qualified Data.Aeson as A
233+import Data.Aeson qualified as A
239import Data.ByteString (ByteString)
234import Data.ByteString (ByteString)
240−import qualified Data.ByteString as B
235+import Data.ByteString qualified as B
241−import qualified Data.ByteString.Lazy as BL
236+import Data.ByteString.Lazy qualified as BL
242−import qualified Data.CaseInsensitive as CI
237+import Data.CaseInsensitive qualified as CI
243import Data.Data (Data)
238import Data.Data (Data)
239+import Data.Default.Class (def)
244import Data.Function (on)
240import Data.Function (on)
245import Data.IORef
241import Data.IORef
246import Data.Kind (Constraint, Type)
242import Data.Kind (Constraint, Type)
247import Data.List (foldl', nubBy)
243import Data.List (foldl', nubBy)
248import Data.List.NonEmpty (NonEmpty (..))
244import Data.List.NonEmpty (NonEmpty (..))
249−import qualified Data.List.NonEmpty as NE
245+import Data.List.NonEmpty qualified as NE
250import Data.Maybe (fromMaybe)
246import Data.Maybe (fromMaybe)
251import Data.Proxy
247import Data.Proxy
252−import Data.Semigroup hiding (Option, option)
248+import Data.Semigroup (Endo (..))
249+import Data.Set qualified as S
253import Data.Text (Text)
250import Data.Text (Text)
251+import Data.Text qualified as T
254−import qualified Data.Text.Encoding as T
252+import Data.Text.Encoding qualified as T
255−import Data.Typeable (Typeable)
253+import Data.Typeable (Typeable, cast)
256import GHC.Generics
254import GHC.Generics
257import GHC.TypeLits
255import GHC.TypeLits
256+import Language.Haskell.TH qualified as TH
257+import Language.Haskell.TH.Quote qualified as TH
258+import Language.Haskell.TH.Syntax qualified as TH
258−import qualified Network.Connection as NC
259+import Network.Connection qualified as NC
259−import qualified Network.HTTP.Client as L
260+import Network.HTTP.Client qualified as L
260−import qualified Network.HTTP.Client.Internal as LI
261+import Network.HTTP.Client.Internal qualified as LI
261−import qualified Network.HTTP.Client.MultipartFormData as LM
262+import Network.HTTP.Client.MultipartFormData qualified as LM
262−import qualified Network.HTTP.Client.TLS as L
263+import Network.HTTP.Client.TLS qualified as L
263−import qualified Network.HTTP.Types as Y
264+import Network.HTTP.Types qualified as Y
264import System.IO.Unsafe (unsafePerformIO)
265import System.IO.Unsafe (unsafePerformIO)
265import Text.URI (URI)
266import Text.URI (URI)
266−import qualified Text.URI as URI
267+import Text.URI qualified as URI
267−import qualified Text.URI.QQ as QQ
268+import Text.URI.QQ qualified as QQ
268−import qualified Web.Authenticate.OAuth as OAuth
269+import Web.Authenticate.OAuth qualified as OAuth
270+import Web.FormUrlEncoded (FromForm (..), ToForm (..))
271+import Web.FormUrlEncoded qualified as Form
269import Web.HttpApiData (ToHttpApiData (..))
272import Web.HttpApiData (ToHttpApiData (..))
271----------------------------------------------------------------------------
274----------------------------------------------------------------------------
@@ -290,7 +293,7 @@ import Web.HttpApiData (ToHttpApiData (..))
291-- @body@ is a body option such as 'NoReqBody' or 'ReqBodyJson'. The
294-- @body@ is a body option such as 'NoReqBody' or 'ReqBodyJson'. The
292-- tutorial has a section about HTTP bodies, but usage is very
295-- tutorial has a section about HTTP bodies, but usage is very
293−-- straightforward and should be clear from the examples below.
296+-- straightforward and should be clear from the examples.
295-- @response@ is a type hint how to make and interpret response of an HTTP
298-- @response@ is a type hint how to make and interpret response of an HTTP
296-- request. Out-of-the-box it can be the following:
299-- request. Out-of-the-box it can be the following:
@@ -418,12 +421,7 @@ req ::
418 -- | Response
421 -- | Response
419 m response
422 m response
420req method url body responseProxy options =
423req method url body responseProxy options =
421− reqBr method url body (options <> extraOptions) getHttpResponse
424+ reqCb method url body responseProxy options pure
424− case acceptHeader responseProxy of
426− Just accept -> header "Accept" accept
428-- | A version of 'req' that does not use one of the predefined instances of
426-- | A version of 'req' that does not use one of the predefined instances of
429-- 'HttpResponse' but instead allows the user to consume @'L.Response'
427-- 'HttpResponse' but instead allows the user to consume @'L.Response'
@@ -448,7 +446,58 @@ reqBr ::
448 (L.Response L.BodyReader -> IO a) ->
446 (L.Response L.BodyReader -> IO a) ->
449 -- | Result
447 -- | Result
451−reqBr method url body options consume = req' method url body options $ \request manager -> do
449+reqBr method url body options consume =
450+ req' method url body options (reqHandler consume)
452+-- | A version of 'req' that takes a callback to modify the 'L.Request', but
453+-- otherwise performs the request identically.
460+ HttpResponse response,
461+ HttpBodyAllowed (AllowsBody method) (ProvidesBody body)
465+ -- | 'Url'—location of resource
467+ -- | Body of the request
469+ -- | A hint how to interpret response
471+ -- | Collection of optional parameters
473+ -- | Callback to modify the request
474+ (L.Request -> m L.Request) ->
477+reqCb method url body responseProxy options adjustRequest =
478+ req' method url body (options <> extraOptions) $ \request manager -> do
479+ request' <- adjustRequest request
480+ reqHandler getHttpResponse request' manager
483+ case acceptHeader responseProxy of
485+ Just accept -> header "Accept" accept
487+-- | The default handler function that the higher-level request functions
488+-- pass to 'req''. Internal function.
493+ -- | How to get final result from a 'L.Response'
494+ (L.Response L.BodyReader -> IO b) ->
495+ -- | 'L.Request' to perform
497+ -- | 'L.Manager' to use
500+reqHandler consume request manager = do
452 HttpConfig {..} <- getHttpConfig
501 HttpConfig {..} <- getHttpConfig
453 let wrapVanilla = handle (throwIO . VanillaHttpException)
502 let wrapVanilla = handle (throwIO . VanillaHttpException)
454 wrapExc = handle (throwIO . LI.toHttpException request)
503 wrapExc = handle (throwIO . LI.toHttpException request)
@@ -464,12 +513,23 @@ reqBr method url body options consume = req' method url body options $ \request
464 r' <- L.responseOpen request manager
513 r' <- L.responseOpen request manager
465 writeIORef rref (Just r')
514 writeIORef rref (Just r')
466 return r'
515 return r'
516+ exceptionRetryPolicies =
518+ ++ [ \retryStatus -> Handler $ \e ->
519+ return $ httpConfigRetryJudgeException retryStatus e
469 httpConfigRetryPolicy
523 httpConfigRetryPolicy
470− (\st r -> return $ httpConfigRetryJudge st r)
524+ (\retryStatus r -> return $ httpConfigRetryJudge retryStatus r)
527+ httpConfigRetryPolicy
528+ exceptionRetryPolicies
471− (const openResponse)
529+ (const openResponse)
472− (preview, r') <- grabPreview bodyPreviewLength r
532+ (preview, r') <- grabPreview httpConfigBodyPreviewLength r
473 mapM_ LI.throwHttp (httpConfigCheckResponse request r' preview)
533 mapM_ LI.throwHttp (httpConfigCheckResponse request r' preview)
474 consume r'
534 consume r'
@@ -518,22 +578,22 @@ req' method url body options m = do
518 nubHeaders
578 nubHeaders
519 <> getRequestMod options
579 <> getRequestMod options
520 <> getRequestMod config
580 <> getRequestMod config
521− <> getRequestMod (Womb body :: Womb "body" body)
581+ <> getRequestMod (Tagged body :: Tagged "body" body)
522 <> getRequestMod url
582 <> getRequestMod url
523− <> getRequestMod (Womb method :: Womb "method" method)
583+ <> getRequestMod (Tagged method :: Tagged "method" method)
524 request <- finalizeRequest options request'
584 request <- finalizeRequest options request'
525 withReqManager (m request)
585 withReqManager (m request)
527-- | Perform an action using the global implicit 'L.Manager' that the rest
587-- | Perform an action using the global implicit 'L.Manager' that the rest
528−-- of the library uses. This allows to reuse connections that the
588+-- of the library uses. This allows us to reuse connections that the
529-- 'L.Manager' controls.
589-- 'L.Manager' controls.
530−withReqManager :: MonadIO m => (L.Manager -> m a) -> m a
590+withReqManager :: (MonadIO m) => (L.Manager -> m a) -> m a
531−withReqManager m = liftIO (readIORef globalManager) >>= m
591+withReqManager m = m globalManager
533−-- | Global 'L.Manager' that 'req' uses. Here we just go with the default
593+-- | The global 'L.Manager' that 'req' uses. Here we just go with the
534−-- settings, so users don't need to deal with this manager stuff at all, but
594+-- default settings, so users don't need to deal with this manager stuff at
535−-- when we create a request, instance 'HttpConfig' can affect the default
595+-- all, but when we create a request, instance 'HttpConfig' can affect the
536−-- settings via 'getHttpConfig'.
596+-- default settings via 'getHttpConfig'.
538-- A note about safety, in case 'unsafePerformIO' looks suspicious to you.
598-- A note about safety, in case 'unsafePerformIO' looks suspicious to you.
539-- The value of 'globalManager' is named and lives on top level. This means
599-- The value of 'globalManager' is named and lives on top level. This means
@@ -541,16 +601,16 @@ withReqManager m = liftIO (readIORef globalManager) >>= m
541-- manager. From that moment on the 'IORef' will be just reused—exactly the
601-- manager. From that moment on the 'IORef' will be just reused—exactly the
542-- behavior we want here in order to maximize connection sharing. GHC could
602-- behavior we want here in order to maximize connection sharing. GHC could
543-- spoil the plan by inlining the definition, hence the @NOINLINE@ pragma.
603-- spoil the plan by inlining the definition, hence the @NOINLINE@ pragma.
544−globalManager :: IORef L.Manager
604+globalManager :: L.Manager
545globalManager = unsafePerformIO $ do
605globalManager = unsafePerformIO $ do
546 context <- NC.initConnectionContext
606 context <- NC.initConnectionContext
547 let settings =
607 let settings =
548 L.mkManagerSettingsContext
608 L.mkManagerSettingsContext
549 (Just context)
609 (Just context)
550− (NC.TLSSettingsSimple False False False)
610+ def
552 manager <- L.newManager settings
612 manager <- L.newManager settings
553− newIORef manager
613+ return manager
554{-# NOINLINE globalManager #-}
614{-# NOINLINE globalManager #-}
556----------------------------------------------------------------------------
616----------------------------------------------------------------------------
@@ -564,13 +624,13 @@ globalManager = unsafePerformIO $ do
564-- When writing a library, keep your API polymorphic in terms of
624-- When writing a library, keep your API polymorphic in terms of
565-- 'MonadHttp', only define instance of 'MonadHttp' in final application.
625-- 'MonadHttp', only define instance of 'MonadHttp' in final application.
566-- Another option is to use a @newtype@-wrapped monad stack and define
626-- Another option is to use a @newtype@-wrapped monad stack and define
567−-- 'MonadHttp' for it. As of version /0.4.0/, the 'Req' monad that follows
627+-- 'MonadHttp' for it. As of the version /0.4.0/, the 'Req' monad that
568−-- this strategy is provided out-of-the-box (see below).
628+-- follows this strategy is provided out-of-the-box (see below).
570-- | A type class for monads that support performing HTTP requests.
630-- | A type class for monads that support performing HTTP requests.
571-- Typically, you only need to define the 'handleHttpException' method
631-- Typically, you only need to define the 'handleHttpException' method
572-- unless you want to tweak 'HttpConfig'.
632-- unless you want to tweak 'HttpConfig'.
573−class MonadIO m => MonadHttp m where
633+class (MonadIO m) => MonadHttp m where
574 -- | This method describes how to deal with 'HttpException' that was
634 -- | This method describes how to deal with 'HttpException' that was
575 -- caught by the library. One option is to re-throw it if you are OK with
635 -- caught by the library. One option is to re-throw it if you are OK with
576 -- exceptions, but if you prefer working with something like
636 -- exceptions, but if you prefer working with something like
@@ -578,17 +638,16 @@ class MonadIO m => MonadHttp m where
578 -- 'Control.Monad.Except.throwError'.
638 -- 'Control.Monad.Except.throwError'.
579 handleHttpException :: HttpException -> m a
639 handleHttpException :: HttpException -> m a
581− -- | Return 'HttpConfig' to be used when performing HTTP requests. Default
641+ -- | Return the 'HttpConfig' to be used when performing HTTP requests.
582− -- implementation returns its 'def' value, which is described in the
642+ -- Default implementation returns its 'def' value, which is described in
583− -- documentation for the type. Common usage pattern with manually defined
643+ -- the documentation for the type. Common usage pattern with manually
584− -- 'getHttpConfig' is to return some hard-coded value, or a value
644+ -- defined 'getHttpConfig' is to return some hard-coded value, or a value
585 -- extracted from 'Control.Monad.Reader.MonadReader' if a more flexible
645 -- extracted from 'Control.Monad.Reader.MonadReader' if a more flexible
586 -- approach to configuration is desirable.
646 -- approach to configuration is desirable.
587 getHttpConfig :: m HttpConfig
647 getHttpConfig :: m HttpConfig
588 getHttpConfig = return defaultHttpConfig
648 getHttpConfig = return defaultHttpConfig
590−-- | 'HttpConfig' contains general and default settings to be used when
650+-- | 'HttpConfig' contains settings to be used when making HTTP requests.
591−-- making HTTP requests.
592data HttpConfig = HttpConfig
651data HttpConfig = HttpConfig
593 { -- | Proxy to use. By default values of @HTTP_PROXY@ and @HTTPS_PROXY@
652 { -- | Proxy to use. By default values of @HTTP_PROXY@ and @HTTPS_PROXY@
594 -- environment variables are respected, this setting overwrites them.
653 -- environment variables are respected, this setting overwrites them.
@@ -632,8 +691,8 @@ data HttpConfig = HttpConfig
632 -- | The retry policy to use for request retrying. By default 'def' is
691 -- | The retry policy to use for request retrying. By default 'def' is
633 -- used (see 'RetryPolicyM').
692 -- used (see 'RetryPolicyM').
635− -- __Note__: signature of this function was changed in the version
694+ -- __Note__: signature of this function was changed to disallow 'IO' in
636− -- /1.0.0/.
695+ -- version /1.0.0/ and then changed back to its current form in /3.1.0/.
638 -- @since 0.3.0
697 -- @since 0.3.0
639 httpConfigRetryPolicy :: RetryPolicyM IO,
698 httpConfigRetryPolicy :: RetryPolicyM IO,
@@ -644,11 +703,21 @@ data HttpConfig = HttpConfig
644 -- /1.0.0/.
703 -- /1.0.0/.
646 -- @since 0.3.0
705 -- @since 0.3.0
647− httpConfigRetryJudge :: forall b. RetryStatus -> L.Response b -> Bool
706+ httpConfigRetryJudge :: forall b. RetryStatus -> L.Response b -> Bool,
707+ -- | Similar to 'httpConfigRetryJudge', but is used to decide when to
708+ -- retry requests that resulted in an exception. By default it retries
709+ -- on response timeout and connection timeout (changed in version
713+ httpConfigRetryJudgeException :: RetryStatus -> SomeException -> Bool,
714+ -- | Max length of preview fragment of response body.
717+ httpConfigBodyPreviewLength :: forall a. (Num a) => a
651−-- | Default value of 'HttpConfig'.
720+-- | The default value of 'HttpConfig'.
653-- @since 2.0.0
722-- @since 2.0.0
654defaultHttpConfig :: HttpConfig
723defaultHttpConfig :: HttpConfig
@@ -670,7 +739,16 @@ defaultHttpConfig =
670 524, -- A timeout occurred
739 524, -- A timeout occurred
671 598, -- (Informal convention) Network read timeout error
740 598, -- (Informal convention) Network read timeout error
672 599 -- (Informal convention) Network connect timeout error
741 599 -- (Informal convention) Network connect timeout error
743+ httpConfigRetryJudgeException = \_ e ->
744+ case fromException e of
745+ Just (L.HttpExceptionRequest _ c) ->
747+ L.ResponseTimeout -> True
748+ L.ConnectionTimeout -> True
751+ httpConfigBodyPreviewLength = 1024
676 statusCode = Y.statusCode . L.responseStatus
754 statusCode = Y.statusCode . L.responseStatus
@@ -683,7 +761,7 @@ instance RequestComponent HttpConfig where
683 LI.requestManagerOverride = httpConfigAltManager
761 LI.requestManagerOverride = httpConfigAltManager
686−-- | A monad that allows to run 'req' in any 'IO'-enabled monad without
764+-- | A monad that allows us to run 'req' in any 'IO'-enabled monad without
687-- having to define new instances.
765-- having to define new instances.
689-- @since 0.4.0
767-- @since 0.4.0
@@ -692,9 +770,19 @@ newtype Req a = Req (ReaderT HttpConfig IO a)
692 ( Functor,
770 ( Functor,
693 Applicative,
771 Applicative,
695− MonadIO
773+ MonadIO,
778+deriving instance MonadThrow Req
781+deriving instance MonadCatch Req
784+deriving instance MonadMask Req
698instance MonadBase IO Req where
786instance MonadBase IO Req where
699 liftBase = liftIO
787 liftBase = liftIO
@@ -709,12 +797,87 @@ instance MonadHttp Req where
709 handleHttpException = Req . lift . throwIO
797 handleHttpException = Req . lift . throwIO
710 getHttpConfig = Req ask
798 getHttpConfig = Req ask
801+instance (MonadHttp m, Monoid w) => MonadHttp (AccumT w m) where
802+ handleHttpException = lift . handleHttpException
803+ getHttpConfig = lift getHttpConfig
806+instance (MonadHttp m) => MonadHttp (ContT r m) where
807+ handleHttpException = lift . handleHttpException
808+ getHttpConfig = lift getHttpConfig
811+instance (MonadHttp m) => MonadHttp (ExceptT e m) where
812+ handleHttpException = lift . handleHttpException
813+ getHttpConfig = lift getHttpConfig
816+instance (MonadHttp m) => MonadHttp (IdentityT m) where
817+ handleHttpException = lift . handleHttpException
818+ getHttpConfig = lift getHttpConfig
821+instance (MonadHttp m) => MonadHttp (MaybeT m) where
822+ handleHttpException = lift . handleHttpException
823+ getHttpConfig = lift getHttpConfig
826+instance (MonadHttp m) => MonadHttp (ReaderT r m) where
827+ handleHttpException = lift . handleHttpException
828+ getHttpConfig = lift getHttpConfig
831+instance (MonadHttp m, Monoid w) => MonadHttp (RWS.CPS.RWST r w s m) where
832+ handleHttpException = lift . handleHttpException
833+ getHttpConfig = lift getHttpConfig
836+instance (MonadHttp m, Monoid w) => MonadHttp (RWS.Lazy.RWST r w s m) where
837+ handleHttpException = lift . handleHttpException
838+ getHttpConfig = lift getHttpConfig
841+instance (MonadHttp m, Monoid w) => MonadHttp (RWS.Strict.RWST r w s m) where
842+ handleHttpException = lift . handleHttpException
843+ getHttpConfig = lift getHttpConfig
846+instance (MonadHttp m) => MonadHttp (SelectT r m) where
847+ handleHttpException = lift . handleHttpException
848+ getHttpConfig = lift getHttpConfig
851+instance (MonadHttp m) => MonadHttp (State.Lazy.StateT s m) where
852+ handleHttpException = lift . handleHttpException
853+ getHttpConfig = lift getHttpConfig
856+instance (MonadHttp m) => MonadHttp (State.Strict.StateT s m) where
857+ handleHttpException = lift . handleHttpException
858+ getHttpConfig = lift getHttpConfig
861+instance (MonadHttp m, Monoid w) => MonadHttp (Writer.CPS.WriterT w m) where
862+ handleHttpException = lift . handleHttpException
863+ getHttpConfig = lift getHttpConfig
866+instance (MonadHttp m, Monoid w) => MonadHttp (Writer.Lazy.WriterT w m) where
867+ handleHttpException = lift . handleHttpException
868+ getHttpConfig = lift getHttpConfig
871+instance (MonadHttp m, Monoid w) => MonadHttp (Writer.Strict.WriterT w m) where
872+ handleHttpException = lift . handleHttpException
873+ getHttpConfig = lift getHttpConfig
712-- | Run a computation in the 'Req' monad with the given 'HttpConfig'. In
875-- | Run a computation in the 'Req' monad with the given 'HttpConfig'. In
713−-- case of exceptional situation an 'HttpException' will be thrown.
876+-- the case of an exceptional situation an 'HttpException' will be thrown.
715-- @since 0.4.0
878-- @since 0.4.0
717− MonadIO m =>
880+ (MonadIO m) =>
718 -- | 'HttpConfig' to use
881 -- | 'HttpConfig' to use
719 HttpConfig ->
882 HttpConfig ->
720 -- | Computation to run
883 -- | Computation to run
@@ -762,14 +925,15 @@ instance HttpMethod PUT where
762 type AllowsBody PUT = 'CanHaveBody
925 type AllowsBody PUT = 'CanHaveBody
763 httpMethodName Proxy = Y.methodPut
926 httpMethodName Proxy = Y.methodPut
765−-- | 'DELETE' method. This data type does not allow having request body with
928+-- | 'DELETE' method. RFC 7231 allows a payload in DELETE but without
766−-- 'DELETE' requests, as it should be. However some APIs may expect 'DELETE'
929+-- semantics.
767−-- requests to have bodies, in that case define your own variation of
930+--
768−-- 'DELETE' method and allow it to have a body.
931+-- __Note__: before version /3.4.0/ this method did not allow request
769data DELETE = DELETE
933data DELETE = DELETE
771instance HttpMethod DELETE where
935instance HttpMethod DELETE where
772− type AllowsBody DELETE = 'NoBody
936+ type AllowsBody DELETE = 'CanHaveBody
773 httpMethodName Proxy = Y.methodDelete
937 httpMethodName Proxy = Y.methodDelete
775-- | 'TRACE' method.
939-- | 'TRACE' method.
@@ -818,7 +982,7 @@ class HttpMethod a where
818 -- | Return name of the method as a 'ByteString'.
982 -- | Return name of the method as a 'ByteString'.
819 httpMethodName :: Proxy a -> ByteString
983 httpMethodName :: Proxy a -> ByteString
821−instance HttpMethod method => RequestComponent (Womb "method" method) where
985+instance (HttpMethod method) => RequestComponent (Tagged "method" method) where
822 getRequestMod _ = Endo $ \x ->
986 getRequestMod _ = Endo $ \x ->
823 x {L.method = httpMethodName (Proxy :: Proxy method)}
987 x {L.method = httpMethodName (Proxy :: Proxy method)}
@@ -860,7 +1024,20 @@ instance HttpMethod method => RequestComponent (Womb "method" method) where
860-- > -- https://%D1%8E%D0%BD%D0%B8%D0%BA%D0%BE%D0%B4.%D1%80%D1%84
1024-- > -- https://%D1%8E%D0%BD%D0%B8%D0%BA%D0%BE%D0%B4.%D1%80%D1%84
861data Url (scheme :: Scheme) = Url Scheme (NonEmpty Text)
1025data Url (scheme :: Scheme) = Url Scheme (NonEmpty Text)
862 -- NOTE The second value is the path segments in reversed order.
1026 -- NOTE The second value is the path segments in reversed order.
863− deriving (Eq, Ord, Show, Data, Typeable, Generic)
1027+ deriving (Eq, Ord, Show, Data, Generic)
1029+type role Url nominal
1031+-- With template-haskell >=2.15 and text >=1.2.4 Lift can be derived, however
1032+-- the derived lift forgets the type of the scheme.
1033+instance (Typeable scheme) => TH.Lift (Url scheme) where
1035+ TH.dataToExpQ (fmap liftText . cast) url `TH.sigE` case url of
1036+ Url Http _ -> [t|Url 'Http|]
1037+ Url Https _ -> [t|Url 'Https|]
1039+ liftText t = TH.AppE (TH.VarE 'T.pack) <$> TH.lift (T.unpack t)
1040+ liftTyped = TH.Code . TH.unsafeTExpCoerce . TH.lift
865-- | Given host name, produce a 'Url' which has “http” as its scheme and
1042-- | Given host name, produce a 'Url' which has “http” as its scheme and
866-- empty path. This also sets port to @80@.
1043-- empty path. This also sets port to @80@.
@@ -872,20 +1049,33 @@ http = Url Http . pure
872https :: Text -> Url 'Https
1049https :: Text -> Url 'Https
873https = Url Https . pure
1050https = Url Https . pure
875−-- | Grow given 'Url' appending a single path segment to it. Note that the
1052+-- | Grow a given 'Url' appending a single path segment to it. Note that the
876-- path segment can be of any type that is an instance of 'ToHttpApiData'.
1053-- path segment can be of any type that is an instance of 'ToHttpApiData'.
877infixl 5 /~
1054infixl 5 /~
879−(/~) :: ToHttpApiData a => Url scheme -> a -> Url scheme
1056+(/~) :: (ToHttpApiData a) => Url scheme -> a -> Url scheme
880Url secure path /~ segment = Url secure (NE.cons (toUrlPiece segment) path)
1057Url secure path /~ segment = Url secure (NE.cons (toUrlPiece segment) path)
882−-- | Type-constrained version of @('/~')@ to remove ambiguity in the cases
1059+-- | A type-constrained version of @('/~')@ to remove ambiguity in the cases
883-- when next URL piece is a 'Data.Text.Text' literal.
1060-- when next URL piece is a 'Data.Text.Text' literal.
884infixl 5 /:
1061infixl 5 /:
886(/:) :: Url scheme -> Text -> Url scheme
1063(/:) :: Url scheme -> Text -> Url scheme
887(/:) = (/~)
1064(/:) = (/~)
1066+-- | Render a 'Url' as 'Text'.
1069+renderUrl :: Url scheme -> Text
1072+ "https://" <> renderParts parts
1074+ "http://" <> renderParts parts
1076+ renderParts parts =
1077+ T.intercalate "/" (reverse $ NE.toList parts)
889-- | The 'useHttpURI' function provides an alternative method to get 'Url'
1079-- | The 'useHttpURI' function provides an alternative method to get 'Url'
890-- (possibly with some 'Option's) from a 'URI'. This is useful when you are
1080-- (possibly with some 'Option's) from a 'URI'. This is useful when you are
891-- given a URL to query dynamically and don't know it beforehand.
1081-- given a URL to query dynamically and don't know it beforehand.
@@ -899,8 +1089,7 @@ useHttpURI uri = do
899 urlHead <- http <$> uriHost uri
1089 urlHead <- http <$> uriHost uri
900 let url = case URI.uriPath uri of
1090 let url = case URI.uriPath uri of
901 Nothing -> urlHead
1091 Nothing -> urlHead
902− Just (_, xs) ->
1092+ Just uriPath -> uriPathToUrl uriPath urlHead
903− foldl' (/:) urlHead (URI.unRText <$> NE.toList xs)
904 return (url, uriOptions uri)
1093 return (url, uriOptions uri)
906-- | Just like 'useHttpURI', but expects the “https” scheme.
1095-- | Just like 'useHttpURI', but expects the “https” scheme.
@@ -912,10 +1101,21 @@ useHttpsURI uri = do
912 urlHead <- https <$> uriHost uri
1101 urlHead <- https <$> uriHost uri
913 let url = case URI.uriPath uri of
1102 let url = case URI.uriPath uri of
914 Nothing -> urlHead
1103 Nothing -> urlHead
915− Just (_, xs) ->
1104+ Just uriPath -> uriPathToUrl uriPath urlHead
916− foldl' (/:) urlHead (URI.unRText <$> NE.toList xs)
917 return (url, uriOptions uri)
1105 return (url, uriOptions uri)
1107+-- | Convert URI path to a 'Url'. Internal.
1111+ (Bool, NonEmpty (URI.RText 'URI.PathPiece)) ->
1114+uriPathToUrl (trailingSlash, xs) urlHead =
1115+ if trailingSlash then path /: T.empty else path
1117+ path = foldl' (/:) urlHead (URI.unRText <$> NE.toList xs)
919-- | A combination of 'useHttpURI' and 'useHttpsURI' for cases when scheme
1119-- | A combination of 'useHttpURI' and 'useHttpsURI' for cases when scheme
920-- is not known in advance.
1120-- is not known in advance.
@@ -937,6 +1137,29 @@ uriHost uri = case URI.uriAuthority uri of
937 Right URI.Authority {..} ->
1137 Right URI.Authority {..} ->
938 Just (URI.unRText authHost)
1138 Just (URI.unRText authHost)
1140+-- | A quasiquoter to build an 'Url' and 'Option' tuple. The type of the
1141+-- generated expression is @('Url' scheme0, 'Option' scheme1)@ with
1142+-- @scheme0@ being either 'Http' or 'Https' depending on the input.
1145+urlQ :: TH.QuasiQuoter
1148+ { quoteExp = \str ->
1149+ case URI.mkURI (T.pack str) of
1150+ Left err -> fail (displayException err)
1151+ Right uri -> case useURI uri of
1152+ Nothing -> fail "Not a HTTP or HTTPS URL"
1155+ [ either (TH.lift . fst) (TH.lift . fst) eurl,
1158+ quotePat = error "This usage is not supported",
1159+ quoteType = error "This usage is not supported",
1160+ quoteDec = error "This usage is not supported"
940-- | An internal helper function to extract 'Option's from a 'URI'.
1163-- | An internal helper function to extract 'Option's from a 'URI'.
941uriOptions :: forall scheme. URI -> Option scheme
1164uriOptions :: forall scheme. URI -> Option scheme
942uriOptions uri =
1165uriOptions uri =
@@ -1009,21 +1232,21 @@ data NoReqBody = NoReqBody
1009instance HttpBody NoReqBody where
1232instance HttpBody NoReqBody where
1010 getRequestBody NoReqBody = L.RequestBodyBS B.empty
1233 getRequestBody NoReqBody = L.RequestBodyBS B.empty
1012−-- | This body option allows to use a JSON object as request body—probably
1235+-- | This body option allows us to use a JSON object as the request
1013−-- the most popular format right now. Just wrap a data type that is an
1236+-- body—probably the most popular format right now. Just wrap a data type
1014−-- instance of 'ToJSON' type class and you are done: it will be converted to
1237+-- that is an instance of 'ToJSON' type class and you are done: it will be
1015−-- JSON and inserted as request body.
1238+-- converted to JSON and inserted as request body.
1017-- This body option sets the @Content-Type@ header to @\"application/json;
1240-- This body option sets the @Content-Type@ header to @\"application/json;
1018-- charset=utf-8\"@ value.
1241-- charset=utf-8\"@ value.
1019newtype ReqBodyJson a = ReqBodyJson a
1242newtype ReqBodyJson a = ReqBodyJson a
1021−instance ToJSON a => HttpBody (ReqBodyJson a) where
1244+instance (ToJSON a) => HttpBody (ReqBodyJson a) where
1022 getRequestBody (ReqBodyJson a) = L.RequestBodyLBS (A.encode a)
1245 getRequestBody (ReqBodyJson a) = L.RequestBodyLBS (A.encode a)
1023 getRequestContentType _ = pure "application/json; charset=utf-8"
1246 getRequestContentType _ = pure "application/json; charset=utf-8"
1025-- | This body option streams request body from a file. It is expected that
1248-- | This body option streams request body from a file. It is expected that
1026−-- the file size does not change during the streaming.
1249+-- the file size does not change during streaming.
1028-- Using of this body option does not set the @Content-Type@ header.
1251-- Using of this body option does not set the @Content-Type@ header.
1029newtype ReqBodyFile = ReqBodyFile FilePath
1252newtype ReqBodyFile = ReqBodyFile FilePath
@@ -1048,12 +1271,11 @@ newtype ReqBodyLbs = ReqBodyLbs BL.ByteString
1048instance HttpBody ReqBodyLbs where
1271instance HttpBody ReqBodyLbs where
1049 getRequestBody (ReqBodyLbs bs) = L.RequestBodyLBS bs
1272 getRequestBody (ReqBodyLbs bs) = L.RequestBodyLBS bs
1051−-- | Form URL-encoded body. This can hold a collection of parameters which
1274+-- | URL-encoded body. This can hold a collection of parameters which are
1052−-- are encoded similarly to query parameters at the end of query string,
1275+-- encoded similarly to query parameters at the end of query string, with
1053−-- with the only difference that they are stored in request body. The
1276+-- the only difference that they are stored in request body. The similarity
1054−-- similarity is reflected in the API as well, as you can use the same
1277+-- is reflected in the API as well, as you can use the same combinators you
1055−-- combinators you would use to add query parameters: @('=:')@ and
1278+-- would use to add query parameters: @('=:')@ and 'queryFlag'.
1058-- This body option sets the @Content-Type@ header to
1280-- This body option sets the @Content-Type@ header to
1059-- @\"application/x-www-form-urlencoded\"@ value.
1281-- @\"application/x-www-form-urlencoded\"@ value.
@@ -1072,6 +1294,13 @@ newtype FormUrlEncodedParam = FormUrlEncodedParam [(Text, Maybe Text)]
1072instance QueryParam FormUrlEncodedParam where
1294instance QueryParam FormUrlEncodedParam where
1073 queryParam name mvalue =
1295 queryParam name mvalue =
1074 FormUrlEncodedParam [(name, toQueryParam <$> mvalue)]
1296 FormUrlEncodedParam [(name, toQueryParam <$> mvalue)]
1297+ queryParamToList (FormUrlEncodedParam p) = p
1299+-- | Use 'formToQuery'.
1302+instance FromForm FormUrlEncodedParam where
1303+ fromForm = Right . formToQuery
1076-- | Multipart form data. Please consult the
1305-- | Multipart form data. Please consult the
1077-- "Network.HTTP.Client.MultipartFormData" module for how to construct
1306-- "Network.HTTP.Client.MultipartFormData" module for how to construct
@@ -1111,7 +1340,7 @@ instance HttpBody ReqBodyMultipart where
1111-- | Create 'ReqBodyMultipart' request body from a collection of 'LM.Part's.
1340-- | Create 'ReqBodyMultipart' request body from a collection of 'LM.Part's.
1113-- @since 0.2.0
1342-- @since 0.2.0
1114−reqBodyMultipart :: MonadIO m => [LM.Part] -> m ReqBodyMultipart
1343+reqBodyMultipart :: (MonadIO m) => [LM.Part] -> m ReqBodyMultipart
1115reqBodyMultipart parts = liftIO $ do
1344reqBodyMultipart parts = liftIO $ do
1116 boundary <- LM.webkitBoundary
1345 boundary <- LM.webkitBoundary
1117 body <- LM.renderParts boundary parts
1346 body <- LM.renderParts boundary parts
@@ -1139,9 +1368,6 @@ type family ProvidesBody body :: CanHaveBody where
1139-- | This type function allows any HTTP body if method says it
1368-- | This type function allows any HTTP body if method says it
1140-- 'CanHaveBody'. When the method says it should have 'NoBody', the only
1369-- 'CanHaveBody'. When the method says it should have 'NoBody', the only
1141-- body option to use is 'NoReqBody'.
1370-- body option to use is 'NoReqBody'.
1143−-- __Note__: users of GHC 8.0.1 and later will see a slightly more friendly
1144−-- error message when method does not allow a body and body is provided.
1145type family
1371type family
1146 HttpBodyAllowed
1372 HttpBodyAllowed
1147 (allowsBody :: CanHaveBody)
1373 (allowsBody :: CanHaveBody)
@@ -1154,8 +1380,8 @@ type family
1154 TypeError
1380 TypeError
1155 ('Text "This HTTP method does not allow attaching a request body.")
1381 ('Text "This HTTP method does not allow attaching a request body.")
1157−instance HttpBody body => RequestComponent (Womb "body" body) where
1383+instance (HttpBody body) => RequestComponent (Tagged "body" body) where
1158− getRequestMod (Womb body) = Endo $ \x ->
1384+ getRequestMod (Tagged body) = Endo $ \x ->
1160 { L.requestBody = getRequestBody body,
1386 { L.requestBody = getRequestBody body,
1161 L.requestHeaders =
1387 L.requestHeaders =
@@ -1184,8 +1410,8 @@ data Option (scheme :: Scheme)
1184 = Option (Endo (Y.QueryText, L.Request)) (Maybe (L.Request -> IO L.Request))
1410 = Option (Endo (Y.QueryText, L.Request)) (Maybe (L.Request -> IO L.Request))
1186-- NOTE 'QueryText' is just [(Text, Maybe Text)], we keep it along with
1412-- NOTE 'QueryText' is just [(Text, Maybe Text)], we keep it along with
1187−-- Request to avoid appending to existing query string in request every
1413+-- Request to avoid appending to an existing query string in request every
1188−-- time new parameter is added. Additional Maybe (L.Request -> IO
1414+-- time new parameter is added. The additional Maybe (L.Request -> IO
1189-- L.Request) is a finalizer that will be applied after all other
1415-- L.Request) is a finalizer that will be applied after all other
1190-- transformations. This is for authentication methods that sign requests
1416-- transformations. This is for authentication methods that sign requests
1191-- based on data in Request.
1417-- based on data in Request.
@@ -1200,6 +1426,12 @@ instance Monoid (Option scheme) where
1200 mempty = Option mempty Nothing
1426 mempty = Option mempty Nothing
1201 mappend = (<>)
1427 mappend = (<>)
1429+-- | Use 'formToQuery'.
1432+instance FromForm (Option scheme) where
1433+ fromForm = Right . formToQuery
1203-- | A helper to create an 'Option' that modifies only collection of query
1435-- | A helper to create an 'Option' that modifies only collection of query
1204-- parameters. This helper is not a part of the public API.
1436-- parameters. This helper is not a part of the public API.
1205withQueryParams :: (Y.QueryText -> Y.QueryText) -> Option scheme
1437withQueryParams :: (Y.QueryText -> Y.QueryText) -> Option scheme
@@ -1218,7 +1450,7 @@ instance RequestComponent (Option scheme) where
1219-- | Finalize given 'L.Request' by applying a finalizer from the given
1451-- | Finalize given 'L.Request' by applying a finalizer from the given
1220-- 'Option' (if it has any).
1452-- 'Option' (if it has any).
1221−finalizeRequest :: MonadIO m => Option scheme -> L.Request -> m L.Request
1453+finalizeRequest :: (MonadIO m) => Option scheme -> L.Request -> m L.Request
1222finalizeRequest (Option _ mfinalizer) = liftIO . fromMaybe pure mfinalizer
1454finalizeRequest (Option _ mfinalizer) = liftIO . fromMaybe pure mfinalizer
1224----------------------------------------------------------------------------
1456----------------------------------------------------------------------------
@@ -1242,7 +1474,7 @@ infix 7 =:
1242(=:) :: (QueryParam param, ToHttpApiData a) => Text -> a -> param
1474(=:) :: (QueryParam param, ToHttpApiData a) => Text -> a -> param
1243name =: value = queryParam name (pure value)
1475name =: value = queryParam name (pure value)
1245−-- | Construct a flag, that is, valueless query parameter. For example, in
1477+-- | Construct a flag, that is, a valueless query parameter. For example, in
1246-- the following URL @\"a\"@ is a flag, while @\"b\"@ is a query parameter
1478-- the following URL @\"a\"@ is a flag, while @\"b\"@ is a query parameter
1247-- with a value:
1479-- with a value:
@@ -1251,9 +1483,27 @@ name =: value = queryParam name (pure value)
1251-- This operator is defined in terms of 'queryParam':
1483-- This operator is defined in terms of 'queryParam':
1253-- > queryFlag name = queryParam name (Nothing :: Maybe ())
1485-- > queryFlag name = queryParam name (Nothing :: Maybe ())
1254−queryFlag :: QueryParam param => Text -> param
1486+queryFlag :: (QueryParam param) => Text -> param
1255queryFlag name = queryParam name (Nothing :: Maybe ())
1487queryFlag name = queryParam name (Nothing :: Maybe ())
1489+-- | Construct query parameters from a 'ToForm' instance. This function
1490+-- produces the same query params as 'Form.urlEncodeAsFormStable'.
1492+-- Note that 'Form.Form' doesn't have the concept of parameters with the
1493+-- empty value (i.e. what you can get by @key =: ""@). If the value is
1494+-- empty, it will be encoded as a valueless parameter (i.e. what you can get
1495+-- by @queryFlag key@).
1498+formToQuery :: (QueryParam param, Monoid param, ToForm f) => f -> param
1499+formToQuery f = mconcat . fmap toParam . Form.toListStable $ toForm f
1501+ toParam (key, val) =
1257-- | A type class for query-parameter-like things. The reason to have an
1507-- | A type class for query-parameter-like things. The reason to have an
1258-- overloaded 'queryParam' is to be able to use it as an 'Option' and as a
1508-- overloaded 'queryParam' is to be able to use it as an 'Option' and as a
1259-- 'FormUrlEncodedParam' when constructing form URL encoded request bodies.
1509-- 'FormUrlEncodedParam' when constructing form URL encoded request bodies.
@@ -1263,11 +1513,17 @@ class QueryParam param where
1263 -- 'Nothing', it won't be included at all (i.e. you create a flag this
1513 -- 'Nothing', it won't be included at all (i.e. you create a flag this
1264 -- way). It's recommended to use @('=:')@ and 'queryFlag' instead of this
1514 -- way). It's recommended to use @('=:')@ and 'queryFlag' instead of this
1265 -- method, because they are easier to read.
1515 -- method, because they are easier to read.
1266− queryParam :: ToHttpApiData a => Text -> Maybe a -> param
1516+ queryParam :: (ToHttpApiData a) => Text -> Maybe a -> param
1518+ -- | Get the query parameter names and values set by 'queryParam'.
1521+ queryParamToList :: param -> [(Text, Maybe Text)]
1268instance QueryParam (Option scheme) where
1523instance QueryParam (Option scheme) where
1269 queryParam name mvalue =
1524 queryParam name mvalue =
1270 withQueryParams ((:) (name, toQueryParam <$> mvalue))
1525 withQueryParams ((:) (name, toQueryParam <$> mvalue))
1526+ queryParamToList (Option f _) = fst $ appEndo f ([], L.defaultRequest)
1272----------------------------------------------------------------------------
1528----------------------------------------------------------------------------
1273-- Request—Optional parameters—Headers
1529-- Request—Optional parameters—Headers
@@ -1291,6 +1547,14 @@ attachHeader :: ByteString -> ByteString -> L.Request -> L.Request
1291attachHeader name value x =
1547attachHeader name value x =
1292 x {L.requestHeaders = (CI.mk name, value) : L.requestHeaders x}
1548 x {L.requestHeaders = (CI.mk name, value) : L.requestHeaders x}
1550+-- | Same as 'header', but with redacted values on print.
1553+headerRedacted :: ByteString -> ByteString -> Option scheme
1554+headerRedacted name value = withRequest $ \x ->
1555+ let y = attachHeader name value x
1556+ in y {L.redactHeaders = CI.mk name `S.insert` L.redactHeaders y}
1294----------------------------------------------------------------------------
1558----------------------------------------------------------------------------
1295-- Request—Optional parameters—Cookies
1559-- Request—Optional parameters—Cookies
@@ -1432,7 +1696,7 @@ customAuth = Option mempty . pure
1433-- | Specify the port to connect to explicitly. Normally, 'Url' you use
1697-- | Specify the port to connect to explicitly. Normally, 'Url' you use
1434-- determines the default port: @80@ for HTTP and @443@ for HTTPS. This
1698-- determines the default port: @80@ for HTTP and @443@ for HTTPS. This
1435−-- 'Option' allows to choose an arbitrary port overwriting the defaults.
1699+-- 'Option' allows us to choose an arbitrary port overwriting the defaults.
1436port :: Int -> Option scheme
1700port :: Int -> Option scheme
1437port n = withRequest $ \x ->
1701port n = withRequest $ \x ->
1438 x {L.port = n}
1702 x {L.port = n}
@@ -1447,8 +1711,8 @@ port n = withRequest $ \x ->
1448-- > decompress (const True)
1712-- > decompress (const True)
1449decompress ::
1713decompress ::
1450− -- | Predicate that is given MIME type, it
1714+ -- | Predicate that is given MIME type, it returns 'True' when content
1451− -- returns 'True' when content should be decompressed on the fly.
1715+ -- should be decompressed on the fly.
1452 (ByteString -> Bool) ->
1716 (ByteString -> Bool) ->
1453 Option scheme
1717 Option scheme
1454decompress f = withRequest $ \x ->
1718decompress f = withRequest $ \x ->
@@ -1479,6 +1743,7 @@ httpVersion major minor = withRequest $ \x ->
1480-- | Make a request and ignore the body of the response.
1744-- | Make a request and ignore the body of the response.
1481newtype IgnoreResponse = IgnoreResponse (L.Response ())
1745newtype IgnoreResponse = IgnoreResponse (L.Response ())
1483instance HttpResponse IgnoreResponse where
1748instance HttpResponse IgnoreResponse where
1484 type HttpResponseBody IgnoreResponse = ()
1749 type HttpResponseBody IgnoreResponse = ()
@@ -1495,8 +1760,9 @@ ignoreResponse = Proxy
1495-- monad in which you use 'req' will determine what to do in the case when
1760-- monad in which you use 'req' will determine what to do in the case when
1496-- parsing fails (the 'JsonHttpException' constructor will be used).
1761-- parsing fails (the 'JsonHttpException' constructor will be used).
1497newtype JsonResponse a = JsonResponse (L.Response a)
1762newtype JsonResponse a = JsonResponse (L.Response a)
1499−instance FromJSON a => HttpResponse (JsonResponse a) where
1765+instance (FromJSON a) => HttpResponse (JsonResponse a) where
1500 type HttpResponseBody (JsonResponse a) = a
1766 type HttpResponseBody (JsonResponse a) = a
1501 toVanillaResponse (JsonResponse r) = r
1767 toVanillaResponse (JsonResponse r) = r
1502 getHttpResponse r = do
1768 getHttpResponse r = do
@@ -1514,6 +1780,7 @@ jsonResponse = Proxy
1514-- | Make a request and interpret the body of the response as a strict
1780-- | Make a request and interpret the body of the response as a strict
1515-- 'ByteString'.
1781-- 'ByteString'.
1516newtype BsResponse = BsResponse (L.Response ByteString)
1782newtype BsResponse = BsResponse (L.Response ByteString)
1518instance HttpResponse BsResponse where
1785instance HttpResponse BsResponse where
1519 type HttpResponseBody BsResponse = ByteString
1786 type HttpResponseBody BsResponse = ByteString
@@ -1530,6 +1797,7 @@ bsResponse = Proxy
1530-- | Make a request and interpret the body of the response as a lazy
1797-- | Make a request and interpret the body of the response as a lazy
1531-- 'BL.ByteString'.
1798-- 'BL.ByteString'.
1532newtype LbsResponse = LbsResponse (L.Response BL.ByteString)
1799newtype LbsResponse = LbsResponse (L.Response BL.ByteString)
1534instance HttpResponse LbsResponse where
1802instance HttpResponse LbsResponse where
1535 type HttpResponseBody LbsResponse = BL.ByteString
1803 type HttpResponseBody LbsResponse = BL.ByteString
@@ -1546,7 +1814,7 @@ lbsResponse = Proxy
1546----------------------------------------------------------------------------
1814----------------------------------------------------------------------------
1547-- Helpers for response interpretations
1815-- Helpers for response interpretations
1549−-- | Fetch beginning of response and return it together with new
1817+-- | Fetch beginning of the response and return it together with a new
1550-- @'L.Response' 'L.BodyReader'@ that can be passed to 'getHttpResponse' and
1818-- @'L.Response' 'L.BodyReader'@ that can be passed to 'getHttpResponse' and
1552grabPreview ::
1820grabPreview ::
@@ -1610,14 +1878,14 @@ brReadN br n = go 0 id id
1611-- | Get the response body.
1879-- | Get the response body.
1612responseBody ::
1880responseBody ::
1613− HttpResponse response =>
1881+ (HttpResponse response) =>
1614 response ->
1882 response ->
1615 HttpResponseBody response
1883 HttpResponseBody response
1616responseBody = L.responseBody . toVanillaResponse
1884responseBody = L.responseBody . toVanillaResponse
1618-- | Get the response status code.
1886-- | Get the response status code.
1619responseStatusCode ::
1887responseStatusCode ::
1620− HttpResponse response =>
1888+ (HttpResponse response) =>
1621 response ->
1889 response ->
1623responseStatusCode =
1891responseStatusCode =
@@ -1625,7 +1893,7 @@ responseStatusCode =
1626-- | Get the response status message.
1894-- | Get the response status message.
1627responseStatusMessage ::
1895responseStatusMessage ::
1628− HttpResponse response =>
1896+ (HttpResponse response) =>
1629 response ->
1897 response ->
1630 ByteString
1898 ByteString
1631responseStatusMessage =
1899responseStatusMessage =
@@ -1633,7 +1901,7 @@ responseStatusMessage =
1634-- | Lookup a particular header from a response.
1902-- | Lookup a particular header from a response.
1635responseHeader ::
1903responseHeader ::
1636− HttpResponse response =>
1904+ (HttpResponse response) =>
1637 -- | Response interpretation
1905 -- | Response interpretation
1638 response ->
1906 response ->
1639 -- | Header to lookup
1907 -- | Header to lookup
@@ -1645,7 +1913,7 @@ responseHeader r h =
1646-- | Get the response 'L.CookieJar'.
1914-- | Get the response 'L.CookieJar'.
1647responseCookieJar ::
1915responseCookieJar ::
1648− HttpResponse response =>
1916+ (HttpResponse response) =>
1649 response ->
1917 response ->
1650 L.CookieJar
1918 L.CookieJar
1651responseCookieJar = L.responseCookieJar . toVanillaResponse
1919responseCookieJar = L.responseCookieJar . toVanillaResponse
@@ -1658,9 +1926,9 @@ responseCookieJar = L.responseCookieJar . toVanillaResponse
1658-- To create a new response interpretation you just need to make your data
1926-- To create a new response interpretation you just need to make your data
1659-- type an instance of the 'HttpResponse' type class.
1927-- type an instance of the 'HttpResponse' type class.
1661−-- | A type class for response interpretations. It allows to describe how to
1929+-- | A type class for response interpretations. It allows us to describe how
1662−-- consume response from a @'L.Response' 'L.BodyReader'@ and produce the
1930+-- to consume the response from a @'L.Response' 'L.BodyReader'@ and produce
1663−-- final result that is to be returned to the user.
1931+-- the final result that is to be returned to the user.
1664class HttpResponse response where
1932class HttpResponse response where
1665 -- | The associated type is the type of body that can be extracted from an
1933 -- | The associated type is the type of body that can be extracted from an
1666 -- instance of 'HttpResponse'.
1934 -- instance of 'HttpResponse'.
@@ -1699,6 +1967,16 @@ class HttpResponse response where
1699 acceptHeader :: Proxy response -> Maybe ByteString
1967 acceptHeader :: Proxy response -> Maybe ByteString
1700 acceptHeader Proxy = Nothing
1968 acceptHeader Proxy = Nothing
1970+-- | This instance has been added to make it easier to inspect 'L.Response'
1971+-- using Req's functions like 'responseStatusCode', 'responseStatusMessage',
1975+instance HttpResponse (L.Response ()) where
1976+ type HttpResponseBody (L.Response ()) = ()
1977+ toVanillaResponse = id
1978+ getHttpResponse = return . void
1702----------------------------------------------------------------------------
1980----------------------------------------------------------------------------
@@ -1724,7 +2002,7 @@ class RequestComponent a where
1724-- method@ and @'HttpBody' body => 'RequestComponent' body@ when it decides
2002-- method@ and @'HttpBody' body => 'RequestComponent' body@ when it decides
1725-- which instance to use (i.e. the constraints are taken into account later,
2003-- which instance to use (i.e. the constraints are taken into account later,
1726-- when instance is already chosen).
2004-- when instance is already chosen).
1727−newtype Womb (tag :: Symbol) a = Womb a
2005+newtype Tagged (tag :: Symbol) a = Tagged a
1729-- | Exceptions that this library throws.
2007-- | Exceptions that this library throws.
1730data HttpException
2008data HttpException
@@ -1733,10 +2011,24 @@ data HttpException
1733 | -- | A wrapper with Aeson-produced 'String' describing why decoding
2011 | -- | A wrapper with Aeson-produced 'String' describing why decoding
1734 -- failed
2012 -- failed
1735 JsonHttpException String
2013 JsonHttpException String
1736− deriving (Show, Typeable, Generic)
2014+ deriving (Show, Generic)
1738instance Exception HttpException
2016instance Exception HttpException
2018+-- | Return 'Just' if the given 'HttpException' is wrapping a http-client's
2019+-- 'L.StatusCodeException'. Otherwise, return 'Nothing'.
2022+isStatusCodeException :: HttpException -> Maybe (L.Response ())
2023+isStatusCodeException
2024+ ( VanillaHttpException
2025+ ( L.HttpExceptionRequest
2027+ (L.StatusCodeException r _)
2030+isStatusCodeException _ = Nothing
1740-- | A simple type isomorphic to 'Bool' that we only have for better error
2032-- | A simple type isomorphic to 'Bool' that we only have for better error
1741-- messages. We use it as a kind and its data constructors as type-level
2033-- messages. We use it as a kind and its data constructors as type-level
@@ -1756,11 +2048,4 @@ data Scheme
1757 | -- | HTTPS
2049 | -- | HTTPS
1759− deriving (Eq, Ord, Show, Data, Typeable, Generic)
2051+ deriving (Eq, Ord, Show, Data, Generic, TH.Lift)
1761−----------------------------------------------------------------------------
1764−-- | Max length of preview fragment of response body.
1765−bodyPreviewLength :: Num a => a
1766−bodyPreviewLength = 1024