@@ -1,19 +1,9 @@
1−{-# LANGUAGE BangPatterns #-}
3{-# LANGUAGE DataKinds #-}
1{-# LANGUAGE DataKinds #-}
4−{-# LANGUAGE DeriveDataTypeable #-}
5−{-# LANGUAGE DeriveGeneric #-}
6−{-# LANGUAGE DeriveLift #-}
7−{-# LANGUAGE FlexibleInstances #-}
8−{-# LANGUAGE GeneralizedNewtypeDeriving #-}
9{-# LANGUAGE LambdaCase #-}
2{-# LANGUAGE LambdaCase #-}
10−{-# LANGUAGE MultiParamTypeClasses #-}
11{-# LANGUAGE OverloadedStrings #-}
3{-# LANGUAGE OverloadedStrings #-}
12{-# LANGUAGE QuasiQuotes #-}
4{-# LANGUAGE QuasiQuotes #-}
13−{-# LANGUAGE RankNTypes #-}
14{-# LANGUAGE RecordWildCards #-}
5{-# LANGUAGE RecordWildCards #-}
15{-# LANGUAGE RoleAnnotations #-}
6{-# LANGUAGE RoleAnnotations #-}
16−{-# LANGUAGE ScopedTypeVariables #-}
17{-# LANGUAGE TemplateHaskellQuotes #-}
7{-# LANGUAGE TemplateHaskellQuotes #-}
18{-# LANGUAGE TypeFamilies #-}
8{-# LANGUAGE TypeFamilies #-}
19{-# LANGUAGE UndecidableInstances #-}
9{-# LANGUAGE UndecidableInstances #-}
@@ -29,61 +19,40 @@
30-- 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
31-- important information is presented first: you learn how to do HTTP
21-- important information is presented first: you learn how to do HTTP
32−-- 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
33-- 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
34-- documentation is written with sufficient coverage of details and
24-- documentation is written with sufficient coverage of details and
35-- 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.
37−-- /(A modest intro goes here, click on 'req' to start making requests.)/
39-- === About the library
27-- === About the library
41−-- 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,
42−-- library that just works without any fooling around.
30+-- and expandable.
44−-- 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
45−-- 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,
46−-- 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
47−-- 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
48−-- should be very approachable and clear to beginners, thus certain
49−-- compromises were made. For example, one cannot currently modify
36+-- clear to beginners, thus certain compromises were made. For example, one
50−-- 'L.ManagerSettings' of the default manager because the library always
37+-- cannot currently modify 'L.ManagerSettings' of the default manager
51−-- uses the same implicit global manager for simplicity and maximal
38+-- because the library always uses the same implicit global manager for
52−-- 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
53−-- settings, but it requires a bit more typing.
40+-- manager with different settings, but it requires more typing.
55−-- “Type-safe” means that the library is protective and eliminates certain
42+-- “Type-safe” means that the library tries to eliminate certain classes of
56−-- classes of errors. For example, we have correct-by-construction 'Url's,
43+-- errors. For example, we have correct-by-construction URLs; it is
57−-- 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
58−-- methods like 'GET' or 'OPTIONS', and the amount of implicit assumptions
45+-- methods like GET or OPTIONS, and the amount of implicit assumptions is
59−-- is minimized by making the user specify his\/her intentions in an
46+-- minimized by making the user specify their intentions in an explicit
60−-- 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
61−-- body or method of request). Authentication methods that assume HTTPS
48+-- method of a request. Authentication methods that assume HTTPS force the
62−-- force the user to use HTTPS at the type level. The library also carefully
49+-- user to use HTTPS at the type level.
63−-- hides underlying types from the lower-level @http-client@ package because
64−-- those types are not safe enough (for example 'L.Request' is an instance
65−-- of 'Data.String.IsString' and, if it's malformed, it will blow up at
68−-- “Expandable” refers to the ability of the library to be expanded without
51+-- “Expandable” refers to the ability to create new components without
69−-- 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
70−-- 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,
71−-- request, create new authorization options, perform a request in a
54+-- create new authorization options, perform a request in a different way,
72−-- different way, and create your own methods to parse and represent a
55+-- and create your own methods to parse a response.
73−-- response. As the user extends the library to satisfy his\/her special
74−-- needs, the new solutions will work just like the built-ins. However, all
75−-- of the common cases are also covered by the library out-of-the-box.
77−-- “High-level” means that there are less details to worry about. The
78−-- library is a result of my experiences as a Haskell consultant. Working
79−-- for several clients, who had very different projects, showed me that the
80−-- library should adapt easily to any particular style of writing Haskell
81−-- applications. For example, some people prefer throwing exceptions, while
82−-- others are concerned with purity. Just define 'handleHttpException'
83−-- accordingly when making your monad instance of 'MonadHttp' and it will
84−-- play together seamlessly. Finally, the library cuts down boilerplate
85−-- considerably, and helps you write concise, easy to read, and maintainable
88-- === Using with other libraries
57-- === Using with other libraries
@@ -112,6 +81,7 @@ module Network.HTTP.Req
112 -- $making-a-request
81 -- $making-a-request
116 withReqManager,
86 withReqManager,
@@ -174,11 +144,13 @@ module Network.HTTP.Req
174 -- $query-parameters
144 -- $query-parameters
176 queryFlag,
146 queryFlag,
177 QueryParam (..),
148 QueryParam (..),
179 -- *** Headers
150 -- *** Headers
181 attachHeader,
152 attachHeader,
183 -- *** Cookies
155 -- *** Cookies
184 -- $cookies
156 -- $cookies
@@ -225,57 +197,78 @@ module Network.HTTP.Req
226 -- * Other
198 -- * Other
227 HttpException (..),
199 HttpException (..),
200+ isStatusCodeException,
228 CanHaveBody (..),
201 CanHaveBody (..),
229 Scheme (..),
202 Scheme (..),
233−import qualified Blaze.ByteString.Builder as BB
206+import Blaze.ByteString.Builder qualified as BB
234import Control.Applicative
207import Control.Applicative
235import Control.Arrow (first, second)
208import Control.Arrow (first, second)
236import Control.Exception hiding (Handler (..), TypeError)
209import Control.Exception hiding (Handler (..), TypeError)
210+import Control.Monad (guard, void, (>=>))
237import Control.Monad.Base
211import Control.Monad.Base
238−import Control.Monad.Catch (Handler (..))
212+import Control.Monad.Catch (Handler (..), MonadCatch, MonadMask, MonadThrow)
239import Control.Monad.IO.Class
213import Control.Monad.IO.Class
240−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)
241import 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
242import Control.Retry
231import Control.Retry
243import Data.Aeson (FromJSON (..), ToJSON (..))
232import Data.Aeson (FromJSON (..), ToJSON (..))
244−import qualified Data.Aeson as A
233+import Data.Aeson qualified as A
245import Data.ByteString (ByteString)
234import Data.ByteString (ByteString)
246−import qualified Data.ByteString as B
235+import Data.ByteString qualified as B
247−import qualified Data.ByteString.Lazy as BL
236+import Data.ByteString.Lazy qualified as BL
248−import qualified Data.CaseInsensitive as CI
237+import Data.CaseInsensitive qualified as CI
249import Data.Data (Data)
238import Data.Data (Data)
239+import Data.Default.Class (def)
250import Data.Function (on)
240import Data.Function (on)
251import Data.IORef
241import Data.IORef
252import Data.Kind (Constraint, Type)
242import Data.Kind (Constraint, Type)
253import Data.List (foldl', nubBy)
243import Data.List (foldl', nubBy)
254import Data.List.NonEmpty (NonEmpty (..))
244import Data.List.NonEmpty (NonEmpty (..))
255−import qualified Data.List.NonEmpty as NE
245+import Data.List.NonEmpty qualified as NE
256import Data.Maybe (fromMaybe)
246import Data.Maybe (fromMaybe)
257import Data.Proxy
247import Data.Proxy
258−import Data.Semigroup hiding (Option, option)
248+import Data.Semigroup (Endo (..))
249+import Data.Set qualified as S
259import Data.Text (Text)
250import Data.Text (Text)
260−import qualified Data.Text as T
251+import Data.Text qualified as T
261−import qualified Data.Text.Encoding as T
252+import Data.Text.Encoding qualified as T
262import Data.Typeable (Typeable, cast)
253import Data.Typeable (Typeable, cast)
263import GHC.Generics
254import GHC.Generics
264import GHC.TypeLits
255import GHC.TypeLits
265−import qualified Language.Haskell.TH as TH
256+import Language.Haskell.TH qualified as TH
266−import qualified Language.Haskell.TH.Quote as TH
257+import Language.Haskell.TH.Quote qualified as TH
267−import qualified Language.Haskell.TH.Syntax as TH
258+import Language.Haskell.TH.Syntax qualified as TH
268−import qualified Network.Connection as NC
259+import Network.Connection qualified as NC
269−import qualified Network.HTTP.Client as L
260+import Network.HTTP.Client qualified as L
270−import qualified Network.HTTP.Client.Internal as LI
261+import Network.HTTP.Client.Internal qualified as LI
271−import qualified Network.HTTP.Client.MultipartFormData as LM
262+import Network.HTTP.Client.MultipartFormData qualified as LM
272−import qualified Network.HTTP.Client.TLS as L
263+import Network.HTTP.Client.TLS qualified as L
273−import qualified Network.HTTP.Types as Y
264+import Network.HTTP.Types qualified as Y
274import System.IO.Unsafe (unsafePerformIO)
265import System.IO.Unsafe (unsafePerformIO)
275import Text.URI (URI)
266import Text.URI (URI)
276−import qualified Text.URI as URI
267+import Text.URI qualified as URI
277−import qualified Text.URI.QQ as QQ
268+import Text.URI.QQ qualified as QQ
278−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
279import Web.HttpApiData (ToHttpApiData (..))
272import Web.HttpApiData (ToHttpApiData (..))
281----------------------------------------------------------------------------
274----------------------------------------------------------------------------
@@ -300,7 +293,7 @@ import Web.HttpApiData (ToHttpApiData (..))
301-- @body@ is a body option such as 'NoReqBody' or 'ReqBodyJson'. The
294-- @body@ is a body option such as 'NoReqBody' or 'ReqBodyJson'. The
302-- tutorial has a section about HTTP bodies, but usage is very
295-- tutorial has a section about HTTP bodies, but usage is very
303−-- straightforward and should be clear from the examples below.
296+-- straightforward and should be clear from the examples.
305-- @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
306-- request. Out-of-the-box it can be the following:
299-- request. Out-of-the-box it can be the following:
@@ -428,12 +421,7 @@ req ::
428 -- | Response
421 -- | Response
429 m response
422 m response
430req method url body responseProxy options =
423req method url body responseProxy options =
431− reqBr method url body (options <> extraOptions) getHttpResponse
424+ reqCb method url body responseProxy options pure
434− case acceptHeader responseProxy of
436− Just accept -> header "Accept" accept
438-- | 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
439-- 'HttpResponse' but instead allows the user to consume @'L.Response'
427-- 'HttpResponse' but instead allows the user to consume @'L.Response'
@@ -458,7 +446,58 @@ reqBr ::
458 (L.Response L.BodyReader -> IO a) ->
446 (L.Response L.BodyReader -> IO a) ->
459 -- | Result
447 -- | Result
461−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
462 HttpConfig {..} <- getHttpConfig
501 HttpConfig {..} <- getHttpConfig
463 let wrapVanilla = handle (throwIO . VanillaHttpException)
502 let wrapVanilla = handle (throwIO . VanillaHttpException)
464 wrapExc = handle (throwIO . LI.toHttpException request)
503 wrapExc = handle (throwIO . LI.toHttpException request)
@@ -490,7 +529,7 @@ reqBr method url body options consume = req' method url body options $ \request
490 (const openResponse)
529 (const openResponse)
493− (preview, r') <- grabPreview bodyPreviewLength r
532+ (preview, r') <- grabPreview httpConfigBodyPreviewLength r
494 mapM_ LI.throwHttp (httpConfigCheckResponse request r' preview)
533 mapM_ LI.throwHttp (httpConfigCheckResponse request r' preview)
495 consume r'
534 consume r'
@@ -539,22 +578,22 @@ req' method url body options m = do
539 nubHeaders
578 nubHeaders
540 <> getRequestMod options
579 <> getRequestMod options
541 <> getRequestMod config
580 <> getRequestMod config
542− <> getRequestMod (Womb body :: Womb "body" body)
581+ <> getRequestMod (Tagged body :: Tagged "body" body)
543 <> getRequestMod url
582 <> getRequestMod url
544− <> getRequestMod (Womb method :: Womb "method" method)
583+ <> getRequestMod (Tagged method :: Tagged "method" method)
545 request <- finalizeRequest options request'
584 request <- finalizeRequest options request'
546 withReqManager (m request)
585 withReqManager (m request)
548-- | 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
549−-- of the library uses. This allows to reuse connections that the
588+-- of the library uses. This allows us to reuse connections that the
550-- 'L.Manager' controls.
589-- 'L.Manager' controls.
551−withReqManager :: MonadIO m => (L.Manager -> m a) -> m a
590+withReqManager :: (MonadIO m) => (L.Manager -> m a) -> m a
552−withReqManager m = liftIO (readIORef globalManager) >>= m
591+withReqManager m = m globalManager
554−-- | 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
555−-- 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
556−-- when we create a request, instance 'HttpConfig' can affect the default
595+-- all, but when we create a request, instance 'HttpConfig' can affect the
557−-- settings via 'getHttpConfig'.
596+-- default settings via 'getHttpConfig'.
559-- A note about safety, in case 'unsafePerformIO' looks suspicious to you.
598-- A note about safety, in case 'unsafePerformIO' looks suspicious to you.
560-- 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
@@ -562,16 +601,16 @@ withReqManager m = liftIO (readIORef globalManager) >>= m
562-- 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
563-- 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
564-- spoil the plan by inlining the definition, hence the @NOINLINE@ pragma.
603-- spoil the plan by inlining the definition, hence the @NOINLINE@ pragma.
565−globalManager :: IORef L.Manager
604+globalManager :: L.Manager
566globalManager = unsafePerformIO $ do
605globalManager = unsafePerformIO $ do
567 context <- NC.initConnectionContext
606 context <- NC.initConnectionContext
568 let settings =
607 let settings =
569 L.mkManagerSettingsContext
608 L.mkManagerSettingsContext
570 (Just context)
609 (Just context)
571− (NC.TLSSettingsSimple False False False)
610+ def
573 manager <- L.newManager settings
612 manager <- L.newManager settings
574− newIORef manager
613+ return manager
575{-# NOINLINE globalManager #-}
614{-# NOINLINE globalManager #-}
577----------------------------------------------------------------------------
616----------------------------------------------------------------------------
@@ -585,13 +624,13 @@ globalManager = unsafePerformIO $ do
585-- When writing a library, keep your API polymorphic in terms of
624-- When writing a library, keep your API polymorphic in terms of
586-- 'MonadHttp', only define instance of 'MonadHttp' in final application.
625-- 'MonadHttp', only define instance of 'MonadHttp' in final application.
587-- 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
588−-- '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
589−-- this strategy is provided out-of-the-box (see below).
628+-- follows this strategy is provided out-of-the-box (see below).
591-- | A type class for monads that support performing HTTP requests.
630-- | A type class for monads that support performing HTTP requests.
592-- Typically, you only need to define the 'handleHttpException' method
631-- Typically, you only need to define the 'handleHttpException' method
593-- unless you want to tweak 'HttpConfig'.
632-- unless you want to tweak 'HttpConfig'.
594−class MonadIO m => MonadHttp m where
633+class (MonadIO m) => MonadHttp m where
595 -- | This method describes how to deal with 'HttpException' that was
634 -- | This method describes how to deal with 'HttpException' that was
596 -- 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
597 -- exceptions, but if you prefer working with something like
636 -- exceptions, but if you prefer working with something like
@@ -599,17 +638,16 @@ class MonadIO m => MonadHttp m where
599 -- 'Control.Monad.Except.throwError'.
638 -- 'Control.Monad.Except.throwError'.
600 handleHttpException :: HttpException -> m a
639 handleHttpException :: HttpException -> m a
602− -- | Return 'HttpConfig' to be used when performing HTTP requests. Default
641+ -- | Return the 'HttpConfig' to be used when performing HTTP requests.
603− -- implementation returns its 'def' value, which is described in the
642+ -- Default implementation returns its 'def' value, which is described in
604− -- documentation for the type. Common usage pattern with manually defined
643+ -- the documentation for the type. Common usage pattern with manually
605− -- 'getHttpConfig' is to return some hard-coded value, or a value
644+ -- defined 'getHttpConfig' is to return some hard-coded value, or a value
606 -- extracted from 'Control.Monad.Reader.MonadReader' if a more flexible
645 -- extracted from 'Control.Monad.Reader.MonadReader' if a more flexible
607 -- approach to configuration is desirable.
646 -- approach to configuration is desirable.
608 getHttpConfig :: m HttpConfig
647 getHttpConfig :: m HttpConfig
609 getHttpConfig = return defaultHttpConfig
648 getHttpConfig = return defaultHttpConfig
611−-- | 'HttpConfig' contains general and default settings to be used when
650+-- | 'HttpConfig' contains settings to be used when making HTTP requests.
612−-- making HTTP requests.
613data HttpConfig = HttpConfig
651data HttpConfig = HttpConfig
614 { -- | 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@
615 -- environment variables are respected, this setting overwrites them.
653 -- environment variables are respected, this setting overwrites them.
@@ -653,8 +691,8 @@ data HttpConfig = HttpConfig
653 -- | 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
654 -- used (see 'RetryPolicyM').
692 -- used (see 'RetryPolicyM').
656− -- __Note__: signature of this function was changed in the version
694+ -- __Note__: signature of this function was changed to disallow 'IO' in
657− -- /1.0.0/.
695+ -- version /1.0.0/ and then changed back to its current form in /3.1.0/.
659 -- @since 0.3.0
697 -- @since 0.3.0
660 httpConfigRetryPolicy :: RetryPolicyM IO,
698 httpConfigRetryPolicy :: RetryPolicyM IO,
@@ -667,14 +705,19 @@ data HttpConfig = HttpConfig
667 -- @since 0.3.0
705 -- @since 0.3.0
668 httpConfigRetryJudge :: forall b. RetryStatus -> L.Response b -> Bool,
706 httpConfigRetryJudge :: forall b. RetryStatus -> L.Response b -> Bool,
669 -- | Similar to 'httpConfigRetryJudge', but is used to decide when to
707 -- | Similar to 'httpConfigRetryJudge', but is used to decide when to
670− -- retry requests that resulted in an exception.
708+ -- retry requests that resulted in an exception. By default it retries
709+ -- on response timeout and connection timeout (changed in version
672 -- @since 3.4.0
712 -- @since 3.4.0
673− httpConfigRetryJudgeException :: RetryStatus -> SomeException -> Bool
713+ httpConfigRetryJudgeException :: RetryStatus -> SomeException -> Bool,
714+ -- | Max length of preview fragment of response body.
717+ httpConfigBodyPreviewLength :: forall a. (Num a) => a
677−-- | Default value of 'HttpConfig'.
720+-- | The default value of 'HttpConfig'.
679-- @since 2.0.0
722-- @since 2.0.0
680defaultHttpConfig :: HttpConfig
723defaultHttpConfig :: HttpConfig
@@ -697,7 +740,15 @@ defaultHttpConfig =
697 598, -- (Informal convention) Network read timeout error
740 598, -- (Informal convention) Network read timeout error
698 599 -- (Informal convention) Network connect timeout error
741 599 -- (Informal convention) Network connect timeout error
700− httpConfigRetryJudgeException = \_ _ -> False
743+ httpConfigRetryJudgeException = \_ e ->
744+ case fromException e of
745+ Just (L.HttpExceptionRequest _ c) ->
747+ L.ResponseTimeout -> True
748+ L.ConnectionTimeout -> True
751+ httpConfigBodyPreviewLength = 1024
703 statusCode = Y.statusCode . L.responseStatus
754 statusCode = Y.statusCode . L.responseStatus
@@ -710,7 +761,7 @@ instance RequestComponent HttpConfig where
710 LI.requestManagerOverride = httpConfigAltManager
761 LI.requestManagerOverride = httpConfigAltManager
713−-- | 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
714-- having to define new instances.
765-- having to define new instances.
716-- @since 0.4.0
767-- @since 0.4.0
@@ -719,9 +770,19 @@ newtype Req a = Req (ReaderT HttpConfig IO a)
719 ( Functor,
770 ( Functor,
720 Applicative,
771 Applicative,
722− MonadIO
773+ MonadIO,
778+deriving instance MonadThrow Req
781+deriving instance MonadCatch Req
784+deriving instance MonadMask Req
725instance MonadBase IO Req where
786instance MonadBase IO Req where
726 liftBase = liftIO
787 liftBase = liftIO
@@ -736,12 +797,87 @@ instance MonadHttp Req where
736 handleHttpException = Req . lift . throwIO
797 handleHttpException = Req . lift . throwIO
737 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
739-- | 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
740−-- case of exceptional situation an 'HttpException' will be thrown.
876+-- the case of an exceptional situation an 'HttpException' will be thrown.
742-- @since 0.4.0
878-- @since 0.4.0
744− MonadIO m =>
880+ (MonadIO m) =>
745 -- | 'HttpConfig' to use
881 -- | 'HttpConfig' to use
746 HttpConfig ->
882 HttpConfig ->
747 -- | Computation to run
883 -- | Computation to run
@@ -846,7 +982,7 @@ class HttpMethod a where
846 -- | Return name of the method as a 'ByteString'.
982 -- | Return name of the method as a 'ByteString'.
847 httpMethodName :: Proxy a -> ByteString
983 httpMethodName :: Proxy a -> ByteString
849−instance HttpMethod method => RequestComponent (Womb "method" method) where
985+instance (HttpMethod method) => RequestComponent (Tagged "method" method) where
850 getRequestMod _ = Endo $ \x ->
986 getRequestMod _ = Endo $ \x ->
851 x {L.method = httpMethodName (Proxy :: Proxy method)}
987 x {L.method = httpMethodName (Proxy :: Proxy method)}
@@ -888,23 +1024,20 @@ instance HttpMethod method => RequestComponent (Womb "method" method) where
888-- > -- 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
889data Url (scheme :: Scheme) = Url Scheme (NonEmpty Text)
1025data Url (scheme :: Scheme) = Url Scheme (NonEmpty Text)
890 -- NOTE The second value is the path segments in reversed order.
1026 -- NOTE The second value is the path segments in reversed order.
891− deriving (Eq, Ord, Show, Data, Typeable, Generic)
1027+ deriving (Eq, Ord, Show, Data, Generic)
893type role Url nominal
1029type role Url nominal
895-- With template-haskell >=2.15 and text >=1.2.4 Lift can be derived, however
1031-- With template-haskell >=2.15 and text >=1.2.4 Lift can be derived, however
896−-- the derived lift forgets the type of scheme.
1032+-- the derived lift forgets the type of the scheme.
897−instance Typeable scheme => TH.Lift (Url scheme) where
1033+instance (Typeable scheme) => TH.Lift (Url scheme) where
898 lift url =
1034 lift url =
899 TH.dataToExpQ (fmap liftText . cast) url `TH.sigE` case url of
1035 TH.dataToExpQ (fmap liftText . cast) url `TH.sigE` case url of
900 Url Http _ -> [t|Url 'Http|]
1036 Url Http _ -> [t|Url 'Http|]
901 Url Https _ -> [t|Url 'Https|]
1037 Url Https _ -> [t|Url 'Https|]
903 liftText t = TH.AppE (TH.VarE 'T.pack) <$> TH.lift (T.unpack t)
1039 liftText t = TH.AppE (TH.VarE 'T.pack) <$> TH.lift (T.unpack t)
905−#if MIN_VERSION_template_haskell(2,16,0)
906− liftTyped url = TH.TExp <$> TH.lift url
1040+ liftTyped = TH.Code . TH.unsafeTExpCoerce . TH.lift
909-- | 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
910-- empty path. This also sets port to @80@.
1043-- empty path. This also sets port to @80@.
@@ -916,14 +1049,14 @@ http = Url Http . pure
916https :: Text -> Url 'Https
1049https :: Text -> Url 'Https
917https = Url Https . pure
1050https = Url Https . pure
919−-- | 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
920-- 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'.
921infixl 5 /~
1054infixl 5 /~
923−(/~) :: ToHttpApiData a => Url scheme -> a -> Url scheme
1056+(/~) :: (ToHttpApiData a) => Url scheme -> a -> Url scheme
924Url secure path /~ segment = Url secure (NE.cons (toUrlPiece segment) path)
1057Url secure path /~ segment = Url secure (NE.cons (toUrlPiece segment) path)
926−-- | Type-constrained version of @('/~')@ to remove ambiguity in the cases
1059+-- | A type-constrained version of @('/~')@ to remove ambiguity in the cases
927-- when next URL piece is a 'Data.Text.Text' literal.
1060-- when next URL piece is a 'Data.Text.Text' literal.
928infixl 5 /:
1061infixl 5 /:
@@ -956,8 +1089,7 @@ useHttpURI uri = do
956 urlHead <- http <$> uriHost uri
1089 urlHead <- http <$> uriHost uri
957 let url = case URI.uriPath uri of
1090 let url = case URI.uriPath uri of
958 Nothing -> urlHead
1091 Nothing -> urlHead
959− Just (_, xs) ->
1092+ Just uriPath -> uriPathToUrl uriPath urlHead
960− foldl' (/:) urlHead (URI.unRText <$> NE.toList xs)
961 return (url, uriOptions uri)
1093 return (url, uriOptions uri)
963-- | Just like 'useHttpURI', but expects the “https” scheme.
1095-- | Just like 'useHttpURI', but expects the “https” scheme.
@@ -969,10 +1101,21 @@ useHttpsURI uri = do
969 urlHead <- https <$> uriHost uri
1101 urlHead <- https <$> uriHost uri
970 let url = case URI.uriPath uri of
1102 let url = case URI.uriPath uri of
971 Nothing -> urlHead
1103 Nothing -> urlHead
972− Just (_, xs) ->
1104+ Just uriPath -> uriPathToUrl uriPath urlHead
973− foldl' (/:) urlHead (URI.unRText <$> NE.toList xs)
974 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)
976-- | A combination of 'useHttpURI' and 'useHttpsURI' for cases when scheme
1119-- | A combination of 'useHttpURI' and 'useHttpsURI' for cases when scheme
977-- is not known in advance.
1120-- is not known in advance.
@@ -1089,21 +1232,21 @@ data NoReqBody = NoReqBody
1089instance HttpBody NoReqBody where
1232instance HttpBody NoReqBody where
1090 getRequestBody NoReqBody = L.RequestBodyBS B.empty
1233 getRequestBody NoReqBody = L.RequestBodyBS B.empty
1092−-- | 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
1093−-- 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
1094−-- 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
1095−-- JSON and inserted as request body.
1238+-- converted to JSON and inserted as request body.
1097-- This body option sets the @Content-Type@ header to @\"application/json;
1240-- This body option sets the @Content-Type@ header to @\"application/json;
1098-- charset=utf-8\"@ value.
1241-- charset=utf-8\"@ value.
1099newtype ReqBodyJson a = ReqBodyJson a
1242newtype ReqBodyJson a = ReqBodyJson a
1101−instance ToJSON a => HttpBody (ReqBodyJson a) where
1244+instance (ToJSON a) => HttpBody (ReqBodyJson a) where
1102 getRequestBody (ReqBodyJson a) = L.RequestBodyLBS (A.encode a)
1245 getRequestBody (ReqBodyJson a) = L.RequestBodyLBS (A.encode a)
1103 getRequestContentType _ = pure "application/json; charset=utf-8"
1246 getRequestContentType _ = pure "application/json; charset=utf-8"
1105-- | 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
1106−-- the file size does not change during the streaming.
1249+-- the file size does not change during streaming.
1108-- 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.
1109newtype ReqBodyFile = ReqBodyFile FilePath
1252newtype ReqBodyFile = ReqBodyFile FilePath
@@ -1128,12 +1271,11 @@ newtype ReqBodyLbs = ReqBodyLbs BL.ByteString
1128instance HttpBody ReqBodyLbs where
1271instance HttpBody ReqBodyLbs where
1129 getRequestBody (ReqBodyLbs bs) = L.RequestBodyLBS bs
1272 getRequestBody (ReqBodyLbs bs) = L.RequestBodyLBS bs
1131−-- | 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
1132−-- 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
1133−-- 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
1134−-- 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
1135−-- combinators you would use to add query parameters: @('=:')@ and
1278+-- would use to add query parameters: @('=:')@ and 'queryFlag'.
1138-- This body option sets the @Content-Type@ header to
1280-- This body option sets the @Content-Type@ header to
1139-- @\"application/x-www-form-urlencoded\"@ value.
1281-- @\"application/x-www-form-urlencoded\"@ value.
@@ -1152,6 +1294,13 @@ newtype FormUrlEncodedParam = FormUrlEncodedParam [(Text, Maybe Text)]
1152instance QueryParam FormUrlEncodedParam where
1294instance QueryParam FormUrlEncodedParam where
1153 queryParam name mvalue =
1295 queryParam name mvalue =
1154 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
1156-- | Multipart form data. Please consult the
1305-- | Multipart form data. Please consult the
1157-- "Network.HTTP.Client.MultipartFormData" module for how to construct
1306-- "Network.HTTP.Client.MultipartFormData" module for how to construct
@@ -1191,7 +1340,7 @@ instance HttpBody ReqBodyMultipart where
1191-- | Create 'ReqBodyMultipart' request body from a collection of 'LM.Part's.
1340-- | Create 'ReqBodyMultipart' request body from a collection of 'LM.Part's.
1193-- @since 0.2.0
1342-- @since 0.2.0
1194−reqBodyMultipart :: MonadIO m => [LM.Part] -> m ReqBodyMultipart
1343+reqBodyMultipart :: (MonadIO m) => [LM.Part] -> m ReqBodyMultipart
1195reqBodyMultipart parts = liftIO $ do
1344reqBodyMultipart parts = liftIO $ do
1196 boundary <- LM.webkitBoundary
1345 boundary <- LM.webkitBoundary
1197 body <- LM.renderParts boundary parts
1346 body <- LM.renderParts boundary parts
@@ -1219,9 +1368,6 @@ type family ProvidesBody body :: CanHaveBody where
1219-- | This type function allows any HTTP body if method says it
1368-- | This type function allows any HTTP body if method says it
1220-- 'CanHaveBody'. When the method says it should have 'NoBody', the only
1369-- 'CanHaveBody'. When the method says it should have 'NoBody', the only
1221-- body option to use is 'NoReqBody'.
1370-- body option to use is 'NoReqBody'.
1223−-- __Note__: users of GHC 8.0.1 and later will see a slightly more friendly
1224−-- error message when method does not allow a body and body is provided.
1225type family
1371type family
1226 HttpBodyAllowed
1372 HttpBodyAllowed
1227 (allowsBody :: CanHaveBody)
1373 (allowsBody :: CanHaveBody)
@@ -1234,8 +1380,8 @@ type family
1234 TypeError
1380 TypeError
1235 ('Text "This HTTP method does not allow attaching a request body.")
1381 ('Text "This HTTP method does not allow attaching a request body.")
1237−instance HttpBody body => RequestComponent (Womb "body" body) where
1383+instance (HttpBody body) => RequestComponent (Tagged "body" body) where
1238− getRequestMod (Womb body) = Endo $ \x ->
1384+ getRequestMod (Tagged body) = Endo $ \x ->
1240 { L.requestBody = getRequestBody body,
1386 { L.requestBody = getRequestBody body,
1241 L.requestHeaders =
1387 L.requestHeaders =
@@ -1264,8 +1410,8 @@ data Option (scheme :: Scheme)
1264 = 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))
1266-- 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
1267−-- Request to avoid appending to existing query string in request every
1413+-- Request to avoid appending to an existing query string in request every
1268−-- time new parameter is added. Additional Maybe (L.Request -> IO
1414+-- time new parameter is added. The additional Maybe (L.Request -> IO
1269-- 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
1270-- transformations. This is for authentication methods that sign requests
1416-- transformations. This is for authentication methods that sign requests
1271-- based on data in Request.
1417-- based on data in Request.
@@ -1280,6 +1426,12 @@ instance Monoid (Option scheme) where
1280 mempty = Option mempty Nothing
1426 mempty = Option mempty Nothing
1281 mappend = (<>)
1427 mappend = (<>)
1429+-- | Use 'formToQuery'.
1432+instance FromForm (Option scheme) where
1433+ fromForm = Right . formToQuery
1283-- | 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
1284-- parameters. This helper is not a part of the public API.
1436-- parameters. This helper is not a part of the public API.
1285withQueryParams :: (Y.QueryText -> Y.QueryText) -> Option scheme
1437withQueryParams :: (Y.QueryText -> Y.QueryText) -> Option scheme
@@ -1298,7 +1450,7 @@ instance RequestComponent (Option scheme) where
1299-- | Finalize given 'L.Request' by applying a finalizer from the given
1451-- | Finalize given 'L.Request' by applying a finalizer from the given
1300-- 'Option' (if it has any).
1452-- 'Option' (if it has any).
1301−finalizeRequest :: MonadIO m => Option scheme -> L.Request -> m L.Request
1453+finalizeRequest :: (MonadIO m) => Option scheme -> L.Request -> m L.Request
1302finalizeRequest (Option _ mfinalizer) = liftIO . fromMaybe pure mfinalizer
1454finalizeRequest (Option _ mfinalizer) = liftIO . fromMaybe pure mfinalizer
1304----------------------------------------------------------------------------
1456----------------------------------------------------------------------------
@@ -1322,7 +1474,7 @@ infix 7 =:
1322(=:) :: (QueryParam param, ToHttpApiData a) => Text -> a -> param
1474(=:) :: (QueryParam param, ToHttpApiData a) => Text -> a -> param
1323name =: value = queryParam name (pure value)
1475name =: value = queryParam name (pure value)
1325−-- | Construct a flag, that is, valueless query parameter. For example, in
1477+-- | Construct a flag, that is, a valueless query parameter. For example, in
1326-- 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
1327-- with a value:
1479-- with a value:
@@ -1331,9 +1483,27 @@ name =: value = queryParam name (pure value)
1331-- This operator is defined in terms of 'queryParam':
1483-- This operator is defined in terms of 'queryParam':
1333-- > queryFlag name = queryParam name (Nothing :: Maybe ())
1485-- > queryFlag name = queryParam name (Nothing :: Maybe ())
1334−queryFlag :: QueryParam param => Text -> param
1486+queryFlag :: (QueryParam param) => Text -> param
1335queryFlag 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) =
1337-- | 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
1338-- 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
1339-- 'FormUrlEncodedParam' when constructing form URL encoded request bodies.
1509-- 'FormUrlEncodedParam' when constructing form URL encoded request bodies.
@@ -1343,11 +1513,17 @@ class QueryParam param where
1343 -- '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
1344 -- way). It's recommended to use @('=:')@ and 'queryFlag' instead of this
1514 -- way). It's recommended to use @('=:')@ and 'queryFlag' instead of this
1345 -- method, because they are easier to read.
1515 -- method, because they are easier to read.
1346− 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)]
1348instance QueryParam (Option scheme) where
1523instance QueryParam (Option scheme) where
1349 queryParam name mvalue =
1524 queryParam name mvalue =
1350 withQueryParams ((:) (name, toQueryParam <$> mvalue))
1525 withQueryParams ((:) (name, toQueryParam <$> mvalue))
1526+ queryParamToList (Option f _) = fst $ appEndo f ([], L.defaultRequest)
1352----------------------------------------------------------------------------
1528----------------------------------------------------------------------------
1353-- Request—Optional parameters—Headers
1529-- Request—Optional parameters—Headers
@@ -1371,6 +1547,14 @@ attachHeader :: ByteString -> ByteString -> L.Request -> L.Request
1371attachHeader name value x =
1547attachHeader name value x =
1372 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}
1374----------------------------------------------------------------------------
1558----------------------------------------------------------------------------
1375-- Request—Optional parameters—Cookies
1559-- Request—Optional parameters—Cookies
@@ -1512,7 +1696,7 @@ customAuth = Option mempty . pure
1513-- | Specify the port to connect to explicitly. Normally, 'Url' you use
1697-- | Specify the port to connect to explicitly. Normally, 'Url' you use
1514-- 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
1515−-- 'Option' allows to choose an arbitrary port overwriting the defaults.
1699+-- 'Option' allows us to choose an arbitrary port overwriting the defaults.
1516port :: Int -> Option scheme
1700port :: Int -> Option scheme
1517port n = withRequest $ \x ->
1701port n = withRequest $ \x ->
1518 x {L.port = n}
1702 x {L.port = n}
@@ -1527,8 +1711,8 @@ port n = withRequest $ \x ->
1528-- > decompress (const True)
1712-- > decompress (const True)
1529decompress ::
1713decompress ::
1530− -- | Predicate that is given MIME type, it
1714+ -- | Predicate that is given MIME type, it returns 'True' when content
1531− -- returns 'True' when content should be decompressed on the fly.
1715+ -- should be decompressed on the fly.
1532 (ByteString -> Bool) ->
1716 (ByteString -> Bool) ->
1533 Option scheme
1717 Option scheme
1534decompress f = withRequest $ \x ->
1718decompress f = withRequest $ \x ->
@@ -1578,7 +1762,7 @@ ignoreResponse = Proxy
1578newtype JsonResponse a = JsonResponse (L.Response a)
1762newtype JsonResponse a = JsonResponse (L.Response a)
1579 deriving (Show)
1763 deriving (Show)
1581−instance FromJSON a => HttpResponse (JsonResponse a) where
1765+instance (FromJSON a) => HttpResponse (JsonResponse a) where
1582 type HttpResponseBody (JsonResponse a) = a
1766 type HttpResponseBody (JsonResponse a) = a
1583 toVanillaResponse (JsonResponse r) = r
1767 toVanillaResponse (JsonResponse r) = r
1584 getHttpResponse r = do
1768 getHttpResponse r = do
@@ -1630,7 +1814,7 @@ lbsResponse = Proxy
1630----------------------------------------------------------------------------
1814----------------------------------------------------------------------------
1631-- Helpers for response interpretations
1815-- Helpers for response interpretations
1633−-- | Fetch beginning of response and return it together with new
1817+-- | Fetch beginning of the response and return it together with a new
1634-- @'L.Response' 'L.BodyReader'@ that can be passed to 'getHttpResponse' and
1818-- @'L.Response' 'L.BodyReader'@ that can be passed to 'getHttpResponse' and
1636grabPreview ::
1820grabPreview ::
@@ -1694,14 +1878,14 @@ brReadN br n = go 0 id id
1695-- | Get the response body.
1879-- | Get the response body.
1696responseBody ::
1880responseBody ::
1697− HttpResponse response =>
1881+ (HttpResponse response) =>
1698 response ->
1882 response ->
1699 HttpResponseBody response
1883 HttpResponseBody response
1700responseBody = L.responseBody . toVanillaResponse
1884responseBody = L.responseBody . toVanillaResponse
1702-- | Get the response status code.
1886-- | Get the response status code.
1703responseStatusCode ::
1887responseStatusCode ::
1704− HttpResponse response =>
1888+ (HttpResponse response) =>
1705 response ->
1889 response ->
1707responseStatusCode =
1891responseStatusCode =
@@ -1709,7 +1893,7 @@ responseStatusCode =
1710-- | Get the response status message.
1894-- | Get the response status message.
1711responseStatusMessage ::
1895responseStatusMessage ::
1712− HttpResponse response =>
1896+ (HttpResponse response) =>
1713 response ->
1897 response ->
1714 ByteString
1898 ByteString
1715responseStatusMessage =
1899responseStatusMessage =
@@ -1717,7 +1901,7 @@ responseStatusMessage =
1718-- | Lookup a particular header from a response.
1902-- | Lookup a particular header from a response.
1719responseHeader ::
1903responseHeader ::
1720− HttpResponse response =>
1904+ (HttpResponse response) =>
1721 -- | Response interpretation
1905 -- | Response interpretation
1722 response ->
1906 response ->
1723 -- | Header to lookup
1907 -- | Header to lookup
@@ -1729,7 +1913,7 @@ responseHeader r h =
1730-- | Get the response 'L.CookieJar'.
1914-- | Get the response 'L.CookieJar'.
1731responseCookieJar ::
1915responseCookieJar ::
1732− HttpResponse response =>
1916+ (HttpResponse response) =>
1733 response ->
1917 response ->
1734 L.CookieJar
1918 L.CookieJar
1735responseCookieJar = L.responseCookieJar . toVanillaResponse
1919responseCookieJar = L.responseCookieJar . toVanillaResponse
@@ -1742,9 +1926,9 @@ responseCookieJar = L.responseCookieJar . toVanillaResponse
1742-- 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
1743-- type an instance of the 'HttpResponse' type class.
1927-- type an instance of the 'HttpResponse' type class.
1745−-- | 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
1746−-- consume response from a @'L.Response' 'L.BodyReader'@ and produce the
1930+-- to consume the response from a @'L.Response' 'L.BodyReader'@ and produce
1747−-- final result that is to be returned to the user.
1931+-- the final result that is to be returned to the user.
1748class HttpResponse response where
1932class HttpResponse response where
1749 -- | 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
1750 -- instance of 'HttpResponse'.
1934 -- instance of 'HttpResponse'.
@@ -1783,6 +1967,16 @@ class HttpResponse response where
1783 acceptHeader :: Proxy response -> Maybe ByteString
1967 acceptHeader :: Proxy response -> Maybe ByteString
1784 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
1786----------------------------------------------------------------------------
1980----------------------------------------------------------------------------
@@ -1808,7 +2002,7 @@ class RequestComponent a where
1808-- method@ and @'HttpBody' body => 'RequestComponent' body@ when it decides
2002-- method@ and @'HttpBody' body => 'RequestComponent' body@ when it decides
1809-- 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,
1810-- when instance is already chosen).
2004-- when instance is already chosen).
1811−newtype Womb (tag :: Symbol) a = Womb a
2005+newtype Tagged (tag :: Symbol) a = Tagged a
1813-- | Exceptions that this library throws.
2007-- | Exceptions that this library throws.
1814data HttpException
2008data HttpException
@@ -1817,10 +2011,24 @@ data HttpException
1817 | -- | A wrapper with Aeson-produced 'String' describing why decoding
2011 | -- | A wrapper with Aeson-produced 'String' describing why decoding
1818 -- failed
2012 -- failed
1819 JsonHttpException String
2013 JsonHttpException String
1820− deriving (Show, Typeable, Generic)
2014+ deriving (Show, Generic)
1822instance 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
1824-- | 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
1825-- 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
@@ -1840,11 +2048,4 @@ data Scheme
1841 | -- | HTTPS
2049 | -- | HTTPS
1843− deriving (Eq, Ord, Show, Data, Typeable, Generic, TH.Lift)
2051+ deriving (Eq, Ord, Show, Data, Generic, TH.Lift)
1845−----------------------------------------------------------------------------
1848−-- | Max length of preview fragment of response body.
1849−bodyPreviewLength :: Num a => a
1850−bodyPreviewLength = 1024