git.iko.soy/typeable/req
on master help sign in
swap
9befc07104 ahead, 0 behind
.github/dependabot.ymlnew file+6
since splitsnapshots
unifiedsplit
@@ -0,0 +1,6 @@
1+version: 2
2+updates:
3+ - package-ecosystem: "github-actions"
4+ directory: "/"
5+ schedule:
6+ interval: "weekly"
.github/workflows/ci.yaml+33−16
@@ -1,30 +1,47 @@
1name: CI
1name: CI
2+on:
2−on: push
3+ push:
4+ branches:
5+ - master
6+ pull_request:
7+ types:
8+ - opened
9+ - synchronize
3jobs:
10jobs:
11+ ormolu:
12+ runs-on: ubuntu-latest
13+ steps:
14+ - uses: actions/checkout@v4
15+ - uses: haskell-actions/run-ormolu@v17
4 build:
16 build:
5 runs-on: ubuntu-latest
17 runs-on: ubuntu-latest
18+ needs: ormolu
6 strategy:
19 strategy:
7 matrix:
20 matrix:
8− cabal: ["3.2"]
21+ cabal: ["3.12"]
9− ghc: ["8.6.5", "8.8.3", "8.10.1"]
22+ ghc: ["9.6.3", "9.8.2", "9.10.1"]
10− env:
11− CONFIG: "--enable-tests --enable-benchmarks --flags=dev"
12 steps:
23 steps:
13− - uses: actions/checkout@v2
24+ - uses: actions/checkout@v4
25+ - uses: haskell-actions/setup@v2
14− - uses: actions/setup-haskell@v1.1.2
26+ id: setup-haskell-cabal
15 with:
27 with:
16 ghc-version: ${{ matrix.ghc }}
28 ghc-version: ${{ matrix.ghc }}
17 cabal-version: ${{ matrix.cabal }}
29 cabal-version: ${{ matrix.cabal }}
30+ - run: cabal update
31+ - run: cabal freeze
18− - uses: actions/cache@v2
32+ - uses: actions/cache@v4.2.3
19 with:
33 with:
20 path: |
34 path: |
21− ~/.cabal/packages
22− ~/.cabal/store
35+ ${{ steps.setup-haskell-cabal.outputs.cabal-store }}
23 dist-newstyle
36 dist-newstyle
24− key: ${{ runner.os }}-${{ matrix.ghc }}
37+ key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }}
25− - run: cabal v2-update
38+ restore-keys: |
39+ ${{ runner.os }}-${{ matrix.ghc }}-
26 - run: cabal format && git diff --exit-code --color=always
40 - run: cabal format && git diff --exit-code --color=always
27− - run: cabal v2-build $CONFIG
41+ - run: cabal build
28− - run: cabal v2-test $CONFIG
42+ - run: |
43+ docker pull kennethreitz/httpbin
44+ docker run -p 1234:80 kennethreitz/httpbin &
45+ cabal test
29− - run: cabal v2-haddock $CONFIG
46+ - run: cabal haddock
30− - run: cabal v2-sdist
47+ - run: cabal sdist
.gitignore+1
@@ -25,5 +25,6 @@ cabal.project.local
25cabal.sandbox.config
25cabal.sandbox.config
26dist-*/
26dist-*/
27dist/
27dist/
28+hie.yaml
28stack.yaml
29stack.yaml
29stack.yaml.lock
30stack.yaml.lock
CHANGELOG.md+87−1
@@ -1,10 +1,96 @@
1+## Req 3.13.4
2+
3+* Fixed empty ciphersuite list when compiling against `tls < 2.0.6`
4+ (see [PR 175](https://github.com/mrkkrp/req/pull/175)). As a side effect, now
5+ compatible with older versions of `crypton-connection` (>= 0.3).
6+
7+## Req 3.13.3
8+
9+* Works with `crypton-connection-0.4` and newer.
10+
11+## Req 3.13.2
12+
13+* Disable the problematic `httpbin-tests` test suite by default. Only enable
14+ it when the `dev` flag is enabled. In that case it is expected that an
15+ httpbin server is run locally at `localhost:1234`.
16+
17+## Req 3.13.1
18+
19+* Switched the non-pure test suite to use https://httpbun.org instead of
20+ https://httpbin.org since the latter proved to be highly unreliable
21+ lately.
22+
23+* Switched from `connection` to `crypton-connection`.
24+
25+* Builds with GHC 9.6.1.
26+
27+## Req 3.13.0
28+
29+* Add `headerRedacted` function to add header fields, which will be with
30+ redacted values on print.
31+
32+## Req 3.12.0
33+
34+* Add `isStatusCodeException` function.
35+* Add `instance HttpResponse (Network.HTTP.Client.Response ())`.
36+
37+## Req 3.11.0
38+
39+* Add the `queryParamToList` method to the `QueryParam` type class.
40+* Add the `formToQuery` function. [Issue 126](https://github.com/mrkkrp/req/issues/126).
41+* Add `FromForm` instances (in the `Web.FormUrlEncoded` module) to the
42+ `Option` and `FormUrlEncodedParam` types.
43+
44+## Req 3.10.0
45+
46+* Add `MonadHttp` instances for `transformers` types.
47+
48+## Req 3.9.2
49+
50+* The test suite works with `aeson-2.x.x.x`.
51+
52+## Req 3.9.1
53+
54+* Builds with GHC 9.0.
55+
56+## Req 3.9.0
57+
58+* The `useHttpURI` and `useHttpsURI` functions now preserve trailing
59+ slashes.
60+
61+## Req 3.8.0
62+
63+* Adjusted the value of the `httpConfigRetryJudgeException` field of
64+ `defaultHttpConfig` to retry on response timeouts and connection timeouts.
65+
66+## Req 3.7.0
67+
68+* Added `reqCb`, a function that allows you to modify the `Request` object
69+ but otherwise performs the requst for you.
70+
71+* Derived `MonadThrow`, `MonadCatch`, and `MonadMask` for the `Req` monad.
72+
73+## Req 3.6.0
74+
75+* Added the `httpConfigBodyPreviewLength` configuration parameter to
76+ `HttpConfig`.
77+
78+## Req 3.5.0
79+
80+* Made `Req` an instance of `MonadUnliftIO`. [Issue
81+ 100](https://github.com/mrkkrp/req/issues/100).
82+
1## Req 3.4.0
83## Req 3.4.0
2
84
3* Requests using `DELETE` method can now have a body. [Issue
85* Requests using `DELETE` method can now have a body. [Issue
4 89](https://github.com/mrkkrp/req/issues/89).
86 89](https://github.com/mrkkrp/req/issues/89).
5
87
6* Added the `httpConfigRetryJudgeException` field to `HttpConfig` so that
88* Added the `httpConfigRetryJudgeException` field to `HttpConfig` so that
7− requests that result in exceptions can be retried.
89+ requests that result in exceptions can be retried. [Issue
90+ 93](https://github.com/mrkkrp/req/issues/93).
91+
92+* Added the function `renderUrl`. [Issue
93+ 83](https://github.com/mrkkrp/req/issues/83).
8
94
9## Req 3.3.0
95## Req 3.3.0
10
96
Network/HTTP/Req.hs+400−185
@@ -1,19 +1,9 @@
1−{-# LANGUAGE BangPatterns #-}
2−{-# LANGUAGE CPP #-}
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 @@
29--
19--
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.
36--
26--
37−-- /(A modest intro goes here, click on 'req' to start making requests.)/
38−--
39-- === About the library
27-- === About the library
40--
28--
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.
43−--
31+--
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.
54−--
41+--
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
66−-- run-time).
67−--
50+--
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.
76−--
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
86−-- code.
87--
56--
88-- === Using with other libraries
57-- === Using with other libraries
89--
58--
@@ -112,6 +81,7 @@ module Network.HTTP.Req
112 -- $making-a-request
81 -- $making-a-request
113 req,
82 req,
114 reqBr,
83 reqBr,
84+ reqCb,
115 req',
85 req',
116 withReqManager,
86 withReqManager,
117
87
@@ -149,6 +119,7 @@ module Network.HTTP.Req
149 useHttpsURI,
119 useHttpsURI,
150 useURI,
120 useURI,
151 urlQ,
121 urlQ,
122+ renderUrl,
152
123
153 -- ** Body
124 -- ** Body
154 -- $body
125 -- $body
@@ -173,11 +144,13 @@ module Network.HTTP.Req
173 -- $query-parameters
144 -- $query-parameters
174 (=:),
145 (=:),
175 queryFlag,
146 queryFlag,
147+ formToQuery,
176 QueryParam (..),
148 QueryParam (..),
177
149
178 -- *** Headers
150 -- *** Headers
179 header,
151 header,
180 attachHeader,
152 attachHeader,
153+ headerRedacted,
181
154
182 -- *** Cookies
155 -- *** Cookies
183 -- $cookies
156 -- $cookies
@@ -224,57 +197,78 @@ module Network.HTTP.Req
224
197
225 -- * Other
198 -- * Other
226 HttpException (..),
199 HttpException (..),
200+ isStatusCodeException,
227 CanHaveBody (..),
201 CanHaveBody (..),
228 Scheme (..),
202 Scheme (..),
229 )
203 )
230where
204where
231
205
232−import qualified Blaze.ByteString.Builder as BB
206+import Blaze.ByteString.Builder qualified as BB
233import Control.Applicative
207import Control.Applicative
234import Control.Arrow (first, second)
208import Control.Arrow (first, second)
235import Control.Exception hiding (Handler (..), TypeError)
209import Control.Exception hiding (Handler (..), TypeError)
210+import Control.Monad (guard, void, (>=>))
236import Control.Monad.Base
211import Control.Monad.Base
237−import Control.Monad.Catch (Handler (..))
212+import Control.Monad.Catch (Handler (..), MonadCatch, MonadMask, MonadThrow)
238import Control.Monad.IO.Class
213import Control.Monad.IO.Class
239−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)
240import 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
241import Control.Retry
231import Control.Retry
242import Data.Aeson (FromJSON (..), ToJSON (..))
232import Data.Aeson (FromJSON (..), ToJSON (..))
243−import qualified Data.Aeson as A
233+import Data.Aeson qualified as A
244import Data.ByteString (ByteString)
234import Data.ByteString (ByteString)
245−import qualified Data.ByteString as B
235+import Data.ByteString qualified as B
246−import qualified Data.ByteString.Lazy as BL
236+import Data.ByteString.Lazy qualified as BL
247−import qualified Data.CaseInsensitive as CI
237+import Data.CaseInsensitive qualified as CI
248import Data.Data (Data)
238import Data.Data (Data)
239+import Data.Default.Class (def)
249import Data.Function (on)
240import Data.Function (on)
250import Data.IORef
241import Data.IORef
251import Data.Kind (Constraint, Type)
242import Data.Kind (Constraint, Type)
252import Data.List (foldl', nubBy)
243import Data.List (foldl', nubBy)
253import Data.List.NonEmpty (NonEmpty (..))
244import Data.List.NonEmpty (NonEmpty (..))
254−import qualified Data.List.NonEmpty as NE
245+import Data.List.NonEmpty qualified as NE
255import Data.Maybe (fromMaybe)
246import Data.Maybe (fromMaybe)
256import Data.Proxy
247import Data.Proxy
257−import Data.Semigroup hiding (Option, option)
248+import Data.Semigroup (Endo (..))
249+import Data.Set qualified as S
258import Data.Text (Text)
250import Data.Text (Text)
259−import qualified Data.Text as T
251+import Data.Text qualified as T
260−import qualified Data.Text.Encoding as T
252+import Data.Text.Encoding qualified as T
261import Data.Typeable (Typeable, cast)
253import Data.Typeable (Typeable, cast)
262import GHC.Generics
254import GHC.Generics
263import GHC.TypeLits
255import GHC.TypeLits
264−import qualified Language.Haskell.TH as TH
256+import Language.Haskell.TH qualified as TH
265−import qualified Language.Haskell.TH.Quote as TH
257+import Language.Haskell.TH.Quote qualified as TH
266−import qualified Language.Haskell.TH.Syntax as TH
258+import Language.Haskell.TH.Syntax qualified as TH
267−import qualified Network.Connection as NC
259+import Network.Connection qualified as NC
268−import qualified Network.HTTP.Client as L
260+import Network.HTTP.Client qualified as L
269−import qualified Network.HTTP.Client.Internal as LI
261+import Network.HTTP.Client.Internal qualified as LI
270−import qualified Network.HTTP.Client.MultipartFormData as LM
262+import Network.HTTP.Client.MultipartFormData qualified as LM
271−import qualified Network.HTTP.Client.TLS as L
263+import Network.HTTP.Client.TLS qualified as L
272−import qualified Network.HTTP.Types as Y
264+import Network.HTTP.Types qualified as Y
273import System.IO.Unsafe (unsafePerformIO)
265import System.IO.Unsafe (unsafePerformIO)
274import Text.URI (URI)
266import Text.URI (URI)
275−import qualified Text.URI as URI
267+import Text.URI qualified as URI
276−import qualified Text.URI.QQ as QQ
268+import Text.URI.QQ qualified as QQ
277−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
278import Web.HttpApiData (ToHttpApiData (..))
272import Web.HttpApiData (ToHttpApiData (..))
279
273
280----------------------------------------------------------------------------
274----------------------------------------------------------------------------
@@ -299,7 +293,7 @@ import Web.HttpApiData (ToHttpApiData (..))
299--
293--
300-- @body@ is a body option such as 'NoReqBody' or 'ReqBodyJson'. The
294-- @body@ is a body option such as 'NoReqBody' or 'ReqBodyJson'. The
301-- tutorial has a section about HTTP bodies, but usage is very
295-- tutorial has a section about HTTP bodies, but usage is very
302−-- straightforward and should be clear from the examples below.
296+-- straightforward and should be clear from the examples.
303--
297--
304-- @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
305-- request. Out-of-the-box it can be the following:
299-- request. Out-of-the-box it can be the following:
@@ -427,12 +421,7 @@ req ::
427 -- | Response
421 -- | Response
428 m response
422 m response
429req method url body responseProxy options =
423req method url body responseProxy options =
430− reqBr method url body (options <> extraOptions) getHttpResponse
424+ reqCb method url body responseProxy options pure
431− where
432− extraOptions =
433− case acceptHeader responseProxy of
434− Nothing -> mempty
435− Just accept -> header "Accept" accept
436
425
437-- | 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
438-- 'HttpResponse' but instead allows the user to consume @'L.Response'
427-- 'HttpResponse' but instead allows the user to consume @'L.Response'
@@ -457,7 +446,58 @@ reqBr ::
457 (L.Response L.BodyReader -> IO a) ->
446 (L.Response L.BodyReader -> IO a) ->
458 -- | Result
447 -- | Result
459 m a
448 m a
460−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)
451+
452+-- | A version of 'req' that takes a callback to modify the 'L.Request', but
453+-- otherwise performs the request identically.
454+--
455+-- @since 3.7.0
456+reqCb ::
457+ ( MonadHttp m,
458+ HttpMethod method,
459+ HttpBody body,
460+ HttpResponse response,
461+ HttpBodyAllowed (AllowsBody method) (ProvidesBody body)
462+ ) =>
463+ -- | HTTP method
464+ method ->
465+ -- | 'Url'—location of resource
466+ Url scheme ->
467+ -- | Body of the request
468+ body ->
469+ -- | A hint how to interpret response
470+ Proxy response ->
471+ -- | Collection of optional parameters
472+ Option scheme ->
473+ -- | Callback to modify the request
474+ (L.Request -> m L.Request) ->
475+ -- | Response
476+ m response
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
481+ where
482+ extraOptions =
483+ case acceptHeader responseProxy of
484+ Nothing -> mempty
485+ Just accept -> header "Accept" accept
486+
487+-- | The default handler function that the higher-level request functions
488+-- pass to 'req''. Internal function.
489+--
490+-- @since 3.7.0
491+reqHandler ::
492+ (MonadHttp m) =>
493+ -- | How to get final result from a 'L.Response'
494+ (L.Response L.BodyReader -> IO b) ->
495+ -- | 'L.Request' to perform
496+ L.Request ->
497+ -- | 'L.Manager' to use
498+ L.Manager ->
499+ m b
500+reqHandler consume request manager = do
461 HttpConfig {..} <- getHttpConfig
501 HttpConfig {..} <- getHttpConfig
462 let wrapVanilla = handle (throwIO . VanillaHttpException)
502 let wrapVanilla = handle (throwIO . VanillaHttpException)
463 wrapExc = handle (throwIO . LI.toHttpException request)
503 wrapExc = handle (throwIO . LI.toHttpException request)
@@ -489,7 +529,7 @@ reqBr method url body options consume = req' method url body options $ \request
489 (const openResponse)
529 (const openResponse)
490 )
530 )
491 )
531 )
492− (preview, r') <- grabPreview bodyPreviewLength r
532+ (preview, r') <- grabPreview httpConfigBodyPreviewLength r
493 mapM_ LI.throwHttp (httpConfigCheckResponse request r' preview)
533 mapM_ LI.throwHttp (httpConfigCheckResponse request r' preview)
494 consume r'
534 consume r'
495 )
535 )
@@ -538,22 +578,22 @@ req' method url body options m = do
538 nubHeaders
578 nubHeaders
539 <> getRequestMod options
579 <> getRequestMod options
540 <> getRequestMod config
580 <> getRequestMod config
541− <> getRequestMod (Womb body :: Womb "body" body)
581+ <> getRequestMod (Tagged body :: Tagged "body" body)
542 <> getRequestMod url
582 <> getRequestMod url
543− <> getRequestMod (Womb method :: Womb "method" method)
583+ <> getRequestMod (Tagged method :: Tagged "method" method)
544 request <- finalizeRequest options request'
584 request <- finalizeRequest options request'
545 withReqManager (m request)
585 withReqManager (m request)
546
586
547-- | 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
548−-- of the library uses. This allows to reuse connections that the
588+-- of the library uses. This allows us to reuse connections that the
549-- 'L.Manager' controls.
589-- 'L.Manager' controls.
550−withReqManager :: MonadIO m => (L.Manager -> m a) -> m a
590+withReqManager :: (MonadIO m) => (L.Manager -> m a) -> m a
551−withReqManager m = liftIO (readIORef globalManager) >>= m
591+withReqManager m = m globalManager
552
592
553−-- | 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
554−-- 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
555−-- when we create a request, instance 'HttpConfig' can affect the default
595+-- all, but when we create a request, instance 'HttpConfig' can affect the
556−-- settings via 'getHttpConfig'.
596+-- default settings via 'getHttpConfig'.
557--
597--
558-- A note about safety, in case 'unsafePerformIO' looks suspicious to you.
598-- A note about safety, in case 'unsafePerformIO' looks suspicious to you.
559-- 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
@@ -561,16 +601,16 @@ withReqManager m = liftIO (readIORef globalManager) >>= m
561-- 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
562-- 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
563-- spoil the plan by inlining the definition, hence the @NOINLINE@ pragma.
603-- spoil the plan by inlining the definition, hence the @NOINLINE@ pragma.
564−globalManager :: IORef L.Manager
604+globalManager :: L.Manager
565globalManager = unsafePerformIO $ do
605globalManager = unsafePerformIO $ do
566 context <- NC.initConnectionContext
606 context <- NC.initConnectionContext
567 let settings =
607 let settings =
568 L.mkManagerSettingsContext
608 L.mkManagerSettingsContext
569 (Just context)
609 (Just context)
570− (NC.TLSSettingsSimple False False False)
610+ def
571 Nothing
611 Nothing
572 manager <- L.newManager settings
612 manager <- L.newManager settings
573− newIORef manager
613+ return manager
574{-# NOINLINE globalManager #-}
614{-# NOINLINE globalManager #-}
575
615
576----------------------------------------------------------------------------
616----------------------------------------------------------------------------
@@ -584,13 +624,13 @@ globalManager = unsafePerformIO $ do
584-- When writing a library, keep your API polymorphic in terms of
624-- When writing a library, keep your API polymorphic in terms of
585-- 'MonadHttp', only define instance of 'MonadHttp' in final application.
625-- 'MonadHttp', only define instance of 'MonadHttp' in final application.
586-- 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
587−-- '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
588−-- this strategy is provided out-of-the-box (see below).
628+-- follows this strategy is provided out-of-the-box (see below).
589
629
590-- | A type class for monads that support performing HTTP requests.
630-- | A type class for monads that support performing HTTP requests.
591-- Typically, you only need to define the 'handleHttpException' method
631-- Typically, you only need to define the 'handleHttpException' method
592-- unless you want to tweak 'HttpConfig'.
632-- unless you want to tweak 'HttpConfig'.
593−class MonadIO m => MonadHttp m where
633+class (MonadIO m) => MonadHttp m where
594 -- | This method describes how to deal with 'HttpException' that was
634 -- | This method describes how to deal with 'HttpException' that was
595 -- 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
596 -- exceptions, but if you prefer working with something like
636 -- exceptions, but if you prefer working with something like
@@ -598,17 +638,16 @@ class MonadIO m => MonadHttp m where
598 -- 'Control.Monad.Except.throwError'.
638 -- 'Control.Monad.Except.throwError'.
599 handleHttpException :: HttpException -> m a
639 handleHttpException :: HttpException -> m a
600
640
601− -- | Return 'HttpConfig' to be used when performing HTTP requests. Default
641+ -- | Return the 'HttpConfig' to be used when performing HTTP requests.
602− -- implementation returns its 'def' value, which is described in the
642+ -- Default implementation returns its 'def' value, which is described in
603− -- documentation for the type. Common usage pattern with manually defined
643+ -- the documentation for the type. Common usage pattern with manually
604− -- 'getHttpConfig' is to return some hard-coded value, or a value
644+ -- defined 'getHttpConfig' is to return some hard-coded value, or a value
605 -- extracted from 'Control.Monad.Reader.MonadReader' if a more flexible
645 -- extracted from 'Control.Monad.Reader.MonadReader' if a more flexible
606 -- approach to configuration is desirable.
646 -- approach to configuration is desirable.
607 getHttpConfig :: m HttpConfig
647 getHttpConfig :: m HttpConfig
608 getHttpConfig = return defaultHttpConfig
648 getHttpConfig = return defaultHttpConfig
609
649
610−-- | 'HttpConfig' contains general and default settings to be used when
650+-- | 'HttpConfig' contains settings to be used when making HTTP requests.
611−-- making HTTP requests.
612data HttpConfig = HttpConfig
651data HttpConfig = HttpConfig
613 { -- | 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@
614 -- environment variables are respected, this setting overwrites them.
653 -- environment variables are respected, this setting overwrites them.
@@ -652,8 +691,8 @@ data HttpConfig = HttpConfig
652 -- | 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
653 -- used (see 'RetryPolicyM').
692 -- used (see 'RetryPolicyM').
654 --
693 --
655− -- __Note__: signature of this function was changed in the version
694+ -- __Note__: signature of this function was changed to disallow 'IO' in
656− -- /1.0.0/.
695+ -- version /1.0.0/ and then changed back to its current form in /3.1.0/.
657 --
696 --
658 -- @since 0.3.0
697 -- @since 0.3.0
659 httpConfigRetryPolicy :: RetryPolicyM IO,
698 httpConfigRetryPolicy :: RetryPolicyM IO,
@@ -666,14 +705,19 @@ data HttpConfig = HttpConfig
666 -- @since 0.3.0
705 -- @since 0.3.0
667 httpConfigRetryJudge :: forall b. RetryStatus -> L.Response b -> Bool,
706 httpConfigRetryJudge :: forall b. RetryStatus -> L.Response b -> Bool,
668 -- | Similar to 'httpConfigRetryJudge', but is used to decide when to
707 -- | Similar to 'httpConfigRetryJudge', but is used to decide when to
669− -- 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
710+ -- /3.8.0/).
670 --
711 --
671 -- @since 3.4.0
712 -- @since 3.4.0
672− httpConfigRetryJudgeException :: RetryStatus -> SomeException -> Bool
713+ httpConfigRetryJudgeException :: RetryStatus -> SomeException -> Bool,
714+ -- | Max length of preview fragment of response body.
715+ --
716+ -- @since 3.6.0
717+ httpConfigBodyPreviewLength :: forall a. (Num a) => a
673 }
718 }
674− deriving (Typeable)
675
719
676−-- | Default value of 'HttpConfig'.
720+-- | The default value of 'HttpConfig'.
677--
721--
678-- @since 2.0.0
722-- @since 2.0.0
679defaultHttpConfig :: HttpConfig
723defaultHttpConfig :: HttpConfig
@@ -696,7 +740,15 @@ defaultHttpConfig =
696 598, -- (Informal convention) Network read timeout error
740 598, -- (Informal convention) Network read timeout error
697 599 -- (Informal convention) Network connect timeout error
741 599 -- (Informal convention) Network connect timeout error
698 ],
742 ],
699− httpConfigRetryJudgeException = \_ _ -> False
743+ httpConfigRetryJudgeException = \_ e ->
744+ case fromException e of
745+ Just (L.HttpExceptionRequest _ c) ->
746+ case c of
747+ L.ResponseTimeout -> True
748+ L.ConnectionTimeout -> True
749+ _ -> False
750+ _ -> False,
751+ httpConfigBodyPreviewLength = 1024
700 }
752 }
701 where
753 where
702 statusCode = Y.statusCode . L.responseStatus
754 statusCode = Y.statusCode . L.responseStatus
@@ -709,7 +761,7 @@ instance RequestComponent HttpConfig where
709 LI.requestManagerOverride = httpConfigAltManager
761 LI.requestManagerOverride = httpConfigAltManager
710 }
762 }
711
763
712−-- | 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
713-- having to define new instances.
765-- having to define new instances.
714--
766--
715-- @since 0.4.0
767-- @since 0.4.0
@@ -718,9 +770,19 @@ newtype Req a = Req (ReaderT HttpConfig IO a)
718 ( Functor,
770 ( Functor,
719 Applicative,
771 Applicative,
720 Monad,
772 Monad,
721− MonadIO
773+ MonadIO,
774+ MonadUnliftIO
722 )
775 )
723
776
777+-- | @since 3.7.0
778+deriving instance MonadThrow Req
779+
780+-- | @since 3.7.0
781+deriving instance MonadCatch Req
782+
783+-- | @since 3.7.0
784+deriving instance MonadMask Req
785+
724instance MonadBase IO Req where
786instance MonadBase IO Req where
725 liftBase = liftIO
787 liftBase = liftIO
726
788
@@ -735,12 +797,87 @@ instance MonadHttp Req where
735 handleHttpException = Req . lift . throwIO
797 handleHttpException = Req . lift . throwIO
736 getHttpConfig = Req ask
798 getHttpConfig = Req ask
737
799
800+-- | @since 3.10.0
801+instance (MonadHttp m, Monoid w) => MonadHttp (AccumT w m) where
802+ handleHttpException = lift . handleHttpException
803+ getHttpConfig = lift getHttpConfig
804+
805+-- | @since 3.10.0
806+instance (MonadHttp m) => MonadHttp (ContT r m) where
807+ handleHttpException = lift . handleHttpException
808+ getHttpConfig = lift getHttpConfig
809+
810+-- | @since 3.10.0
811+instance (MonadHttp m) => MonadHttp (ExceptT e m) where
812+ handleHttpException = lift . handleHttpException
813+ getHttpConfig = lift getHttpConfig
814+
815+-- | @since 3.10.0
816+instance (MonadHttp m) => MonadHttp (IdentityT m) where
817+ handleHttpException = lift . handleHttpException
818+ getHttpConfig = lift getHttpConfig
819+
820+-- | @since 3.10.0
821+instance (MonadHttp m) => MonadHttp (MaybeT m) where
822+ handleHttpException = lift . handleHttpException
823+ getHttpConfig = lift getHttpConfig
824+
825+-- | @since 3.10.0
826+instance (MonadHttp m) => MonadHttp (ReaderT r m) where
827+ handleHttpException = lift . handleHttpException
828+ getHttpConfig = lift getHttpConfig
829+
830+-- | @since 3.10.0
831+instance (MonadHttp m, Monoid w) => MonadHttp (RWS.CPS.RWST r w s m) where
832+ handleHttpException = lift . handleHttpException
833+ getHttpConfig = lift getHttpConfig
834+
835+-- | @since 3.10.0
836+instance (MonadHttp m, Monoid w) => MonadHttp (RWS.Lazy.RWST r w s m) where
837+ handleHttpException = lift . handleHttpException
838+ getHttpConfig = lift getHttpConfig
839+
840+-- | @since 3.10.0
841+instance (MonadHttp m, Monoid w) => MonadHttp (RWS.Strict.RWST r w s m) where
842+ handleHttpException = lift . handleHttpException
843+ getHttpConfig = lift getHttpConfig
844+
845+-- | @since 3.10.0
846+instance (MonadHttp m) => MonadHttp (SelectT r m) where
847+ handleHttpException = lift . handleHttpException
848+ getHttpConfig = lift getHttpConfig
849+
850+-- | @since 3.10.0
851+instance (MonadHttp m) => MonadHttp (State.Lazy.StateT s m) where
852+ handleHttpException = lift . handleHttpException
853+ getHttpConfig = lift getHttpConfig
854+
855+-- | @since 3.10.0
856+instance (MonadHttp m) => MonadHttp (State.Strict.StateT s m) where
857+ handleHttpException = lift . handleHttpException
858+ getHttpConfig = lift getHttpConfig
859+
860+-- | @since 3.10.0
861+instance (MonadHttp m, Monoid w) => MonadHttp (Writer.CPS.WriterT w m) where
862+ handleHttpException = lift . handleHttpException
863+ getHttpConfig = lift getHttpConfig
864+
865+-- | @since 3.10.0
866+instance (MonadHttp m, Monoid w) => MonadHttp (Writer.Lazy.WriterT w m) where
867+ handleHttpException = lift . handleHttpException
868+ getHttpConfig = lift getHttpConfig
869+
870+-- | @since 3.10.0
871+instance (MonadHttp m, Monoid w) => MonadHttp (Writer.Strict.WriterT w m) where
872+ handleHttpException = lift . handleHttpException
873+ getHttpConfig = lift getHttpConfig
874+
738-- | 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
739−-- case of exceptional situation an 'HttpException' will be thrown.
876+-- the case of an exceptional situation an 'HttpException' will be thrown.
740--
877--
741-- @since 0.4.0
878-- @since 0.4.0
742runReq ::
879runReq ::
743− MonadIO m =>
880+ (MonadIO m) =>
744 -- | 'HttpConfig' to use
881 -- | 'HttpConfig' to use
745 HttpConfig ->
882 HttpConfig ->
746 -- | Computation to run
883 -- | Computation to run
@@ -845,7 +982,7 @@ class HttpMethod a where
845 -- | Return name of the method as a 'ByteString'.
982 -- | Return name of the method as a 'ByteString'.
846 httpMethodName :: Proxy a -> ByteString
983 httpMethodName :: Proxy a -> ByteString
847
984
848−instance HttpMethod method => RequestComponent (Womb "method" method) where
985+instance (HttpMethod method) => RequestComponent (Tagged "method" method) where
849 getRequestMod _ = Endo $ \x ->
986 getRequestMod _ = Endo $ \x ->
850 x {L.method = httpMethodName (Proxy :: Proxy method)}
987 x {L.method = httpMethodName (Proxy :: Proxy method)}
851
988
@@ -887,23 +1024,20 @@ instance HttpMethod method => RequestComponent (Womb "method" method) where
887-- > -- 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
888data Url (scheme :: Scheme) = Url Scheme (NonEmpty Text)
1025data Url (scheme :: Scheme) = Url Scheme (NonEmpty Text)
889 -- NOTE The second value is the path segments in reversed order.
1026 -- NOTE The second value is the path segments in reversed order.
890− deriving (Eq, Ord, Show, Data, Typeable, Generic)
1027+ deriving (Eq, Ord, Show, Data, Generic)
891
1028
892type role Url nominal
1029type role Url nominal
893
1030
894-- 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
895−-- the derived lift forgets the type of scheme.
1032+-- the derived lift forgets the type of the scheme.
896−instance Typeable scheme => TH.Lift (Url scheme) where
1033+instance (Typeable scheme) => TH.Lift (Url scheme) where
897 lift url =
1034 lift url =
898 TH.dataToExpQ (fmap liftText . cast) url `TH.sigE` case url of
1035 TH.dataToExpQ (fmap liftText . cast) url `TH.sigE` case url of
899 Url Http _ -> [t|Url 'Http|]
1036 Url Http _ -> [t|Url 'Http|]
900 Url Https _ -> [t|Url 'Https|]
1037 Url Https _ -> [t|Url 'Https|]
901 where
1038 where
902 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)
903−
904−#if MIN_VERSION_template_haskell(2,16,0)
905− liftTyped url = TH.TExp <$> TH.lift url
1040+ liftTyped = TH.Code . TH.unsafeTExpCoerce . TH.lift
906−#endif
907
1041
908-- | 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
909-- empty path. This also sets port to @80@.
1043-- empty path. This also sets port to @80@.
@@ -915,20 +1049,33 @@ http = Url Http . pure
915https :: Text -> Url 'Https
1049https :: Text -> Url 'Https
916https = Url Https . pure
1050https = Url Https . pure
917
1051
918−-- | 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
919-- 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'.
920infixl 5 /~
1054infixl 5 /~
921
1055
922−(/~) :: ToHttpApiData a => Url scheme -> a -> Url scheme
1056+(/~) :: (ToHttpApiData a) => Url scheme -> a -> Url scheme
923Url secure path /~ segment = Url secure (NE.cons (toUrlPiece segment) path)
1057Url secure path /~ segment = Url secure (NE.cons (toUrlPiece segment) path)
924
1058
925−-- | Type-constrained version of @('/~')@ to remove ambiguity in the cases
1059+-- | A type-constrained version of @('/~')@ to remove ambiguity in the cases
926-- when next URL piece is a 'Data.Text.Text' literal.
1060-- when next URL piece is a 'Data.Text.Text' literal.
927infixl 5 /:
1061infixl 5 /:
928
1062
929(/:) :: Url scheme -> Text -> Url scheme
1063(/:) :: Url scheme -> Text -> Url scheme
930(/:) = (/~)
1064(/:) = (/~)
931
1065
1066+-- | Render a 'Url' as 'Text'.
1067+--
1068+-- @since 3.4.0
1069+renderUrl :: Url scheme -> Text
1070+renderUrl = \case
1071+ Url Https parts ->
1072+ "https://" <> renderParts parts
1073+ Url Http parts ->
1074+ "http://" <> renderParts parts
1075+ where
1076+ renderParts parts =
1077+ T.intercalate "/" (reverse $ NE.toList parts)
1078+
932-- | The 'useHttpURI' function provides an alternative method to get 'Url'
1079-- | The 'useHttpURI' function provides an alternative method to get 'Url'
933-- (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
934-- 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.
@@ -942,8 +1089,7 @@ useHttpURI uri = do
942 urlHead <- http <$> uriHost uri
1089 urlHead <- http <$> uriHost uri
943 let url = case URI.uriPath uri of
1090 let url = case URI.uriPath uri of
944 Nothing -> urlHead
1091 Nothing -> urlHead
945− Just (_, xs) ->
1092+ Just uriPath -> uriPathToUrl uriPath urlHead
946− foldl' (/:) urlHead (URI.unRText <$> NE.toList xs)
947 return (url, uriOptions uri)
1093 return (url, uriOptions uri)
948
1094
949-- | Just like 'useHttpURI', but expects the “https” scheme.
1095-- | Just like 'useHttpURI', but expects the “https” scheme.
@@ -955,10 +1101,21 @@ useHttpsURI uri = do
955 urlHead <- https <$> uriHost uri
1101 urlHead <- https <$> uriHost uri
956 let url = case URI.uriPath uri of
1102 let url = case URI.uriPath uri of
957 Nothing -> urlHead
1103 Nothing -> urlHead
958− Just (_, xs) ->
1104+ Just uriPath -> uriPathToUrl uriPath urlHead
959− foldl' (/:) urlHead (URI.unRText <$> NE.toList xs)
960 return (url, uriOptions uri)
1105 return (url, uriOptions uri)
961
1106
1107+-- | Convert URI path to a 'Url'. Internal.
1108+--
1109+-- @since 3.9.0
1110+uriPathToUrl ::
1111+ (Bool, NonEmpty (URI.RText 'URI.PathPiece)) ->
1112+ Url scheme ->
1113+ Url scheme
1114+uriPathToUrl (trailingSlash, xs) urlHead =
1115+ if trailingSlash then path /: T.empty else path
1116+ where
1117+ path = foldl' (/:) urlHead (URI.unRText <$> NE.toList xs)
1118+
962-- | A combination of 'useHttpURI' and 'useHttpsURI' for cases when scheme
1119-- | A combination of 'useHttpURI' and 'useHttpsURI' for cases when scheme
963-- is not known in advance.
1120-- is not known in advance.
964--
1121--
@@ -1075,21 +1232,21 @@ data NoReqBody = NoReqBody
1075instance HttpBody NoReqBody where
1232instance HttpBody NoReqBody where
1076 getRequestBody NoReqBody = L.RequestBodyBS B.empty
1233 getRequestBody NoReqBody = L.RequestBodyBS B.empty
1077
1234
1078−-- | 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
1079−-- 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
1080−-- 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
1081−-- JSON and inserted as request body.
1238+-- converted to JSON and inserted as request body.
1082--
1239--
1083-- This body option sets the @Content-Type@ header to @\"application/json;
1240-- This body option sets the @Content-Type@ header to @\"application/json;
1084-- charset=utf-8\"@ value.
1241-- charset=utf-8\"@ value.
1085newtype ReqBodyJson a = ReqBodyJson a
1242newtype ReqBodyJson a = ReqBodyJson a
1086
1243
1087−instance ToJSON a => HttpBody (ReqBodyJson a) where
1244+instance (ToJSON a) => HttpBody (ReqBodyJson a) where
1088 getRequestBody (ReqBodyJson a) = L.RequestBodyLBS (A.encode a)
1245 getRequestBody (ReqBodyJson a) = L.RequestBodyLBS (A.encode a)
1089 getRequestContentType _ = pure "application/json; charset=utf-8"
1246 getRequestContentType _ = pure "application/json; charset=utf-8"
1090
1247
1091-- | 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
1092−-- the file size does not change during the streaming.
1249+-- the file size does not change during streaming.
1093--
1250--
1094-- 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.
1095newtype ReqBodyFile = ReqBodyFile FilePath
1252newtype ReqBodyFile = ReqBodyFile FilePath
@@ -1114,12 +1271,11 @@ newtype ReqBodyLbs = ReqBodyLbs BL.ByteString
1114instance HttpBody ReqBodyLbs where
1271instance HttpBody ReqBodyLbs where
1115 getRequestBody (ReqBodyLbs bs) = L.RequestBodyLBS bs
1272 getRequestBody (ReqBodyLbs bs) = L.RequestBodyLBS bs
1116
1273
1117−-- | 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
1118−-- 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
1119−-- 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
1120−-- 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
1121−-- combinators you would use to add query parameters: @('=:')@ and
1278+-- would use to add query parameters: @('=:')@ and 'queryFlag'.
1122−-- 'queryFlag'.
1123--
1279--
1124-- This body option sets the @Content-Type@ header to
1280-- This body option sets the @Content-Type@ header to
1125-- @\"application/x-www-form-urlencoded\"@ value.
1281-- @\"application/x-www-form-urlencoded\"@ value.
@@ -1138,6 +1294,13 @@ newtype FormUrlEncodedParam = FormUrlEncodedParam [(Text, Maybe Text)]
1138instance QueryParam FormUrlEncodedParam where
1294instance QueryParam FormUrlEncodedParam where
1139 queryParam name mvalue =
1295 queryParam name mvalue =
1140 FormUrlEncodedParam [(name, toQueryParam <$> mvalue)]
1296 FormUrlEncodedParam [(name, toQueryParam <$> mvalue)]
1297+ queryParamToList (FormUrlEncodedParam p) = p
1298+
1299+-- | Use 'formToQuery'.
1300+--
1301+-- @since 3.11.0
1302+instance FromForm FormUrlEncodedParam where
1303+ fromForm = Right . formToQuery
1141
1304
1142-- | Multipart form data. Please consult the
1305-- | Multipart form data. Please consult the
1143-- "Network.HTTP.Client.MultipartFormData" module for how to construct
1306-- "Network.HTTP.Client.MultipartFormData" module for how to construct
@@ -1177,7 +1340,7 @@ instance HttpBody ReqBodyMultipart where
1177-- | Create 'ReqBodyMultipart' request body from a collection of 'LM.Part's.
1340-- | Create 'ReqBodyMultipart' request body from a collection of 'LM.Part's.
1178--
1341--
1179-- @since 0.2.0
1342-- @since 0.2.0
1180−reqBodyMultipart :: MonadIO m => [LM.Part] -> m ReqBodyMultipart
1343+reqBodyMultipart :: (MonadIO m) => [LM.Part] -> m ReqBodyMultipart
1181reqBodyMultipart parts = liftIO $ do
1344reqBodyMultipart parts = liftIO $ do
1182 boundary <- LM.webkitBoundary
1345 boundary <- LM.webkitBoundary
1183 body <- LM.renderParts boundary parts
1346 body <- LM.renderParts boundary parts
@@ -1205,9 +1368,6 @@ type family ProvidesBody body :: CanHaveBody where
1205-- | This type function allows any HTTP body if method says it
1368-- | This type function allows any HTTP body if method says it
1206-- 'CanHaveBody'. When the method says it should have 'NoBody', the only
1369-- 'CanHaveBody'. When the method says it should have 'NoBody', the only
1207-- body option to use is 'NoReqBody'.
1370-- body option to use is 'NoReqBody'.
1208−--
1209−-- __Note__: users of GHC 8.0.1 and later will see a slightly more friendly
1210−-- error message when method does not allow a body and body is provided.
1211type family
1371type family
1212 HttpBodyAllowed
1372 HttpBodyAllowed
1213 (allowsBody :: CanHaveBody)
1373 (allowsBody :: CanHaveBody)
@@ -1220,8 +1380,8 @@ type family
1220 TypeError
1380 TypeError
1221 ('Text "This HTTP method does not allow attaching a request body.")
1381 ('Text "This HTTP method does not allow attaching a request body.")
1222
1382
1223−instance HttpBody body => RequestComponent (Womb "body" body) where
1383+instance (HttpBody body) => RequestComponent (Tagged "body" body) where
1224− getRequestMod (Womb body) = Endo $ \x ->
1384+ getRequestMod (Tagged body) = Endo $ \x ->
1225 x
1385 x
1226 { L.requestBody = getRequestBody body,
1386 { L.requestBody = getRequestBody body,
1227 L.requestHeaders =
1387 L.requestHeaders =
@@ -1250,8 +1410,8 @@ data Option (scheme :: Scheme)
1250 = 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))
1251
1411
1252-- 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
1253−-- Request to avoid appending to existing query string in request every
1413+-- Request to avoid appending to an existing query string in request every
1254−-- time new parameter is added. Additional Maybe (L.Request -> IO
1414+-- time new parameter is added. The additional Maybe (L.Request -> IO
1255-- 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
1256-- transformations. This is for authentication methods that sign requests
1416-- transformations. This is for authentication methods that sign requests
1257-- based on data in Request.
1417-- based on data in Request.
@@ -1266,6 +1426,12 @@ instance Monoid (Option scheme) where
1266 mempty = Option mempty Nothing
1426 mempty = Option mempty Nothing
1267 mappend = (<>)
1427 mappend = (<>)
1268
1428
1429+-- | Use 'formToQuery'.
1430+--
1431+-- @since 3.11.0
1432+instance FromForm (Option scheme) where
1433+ fromForm = Right . formToQuery
1434+
1269-- | 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
1270-- parameters. This helper is not a part of the public API.
1436-- parameters. This helper is not a part of the public API.
1271withQueryParams :: (Y.QueryText -> Y.QueryText) -> Option scheme
1437withQueryParams :: (Y.QueryText -> Y.QueryText) -> Option scheme
@@ -1284,7 +1450,7 @@ instance RequestComponent (Option scheme) where
1284
1450
1285-- | Finalize given 'L.Request' by applying a finalizer from the given
1451-- | Finalize given 'L.Request' by applying a finalizer from the given
1286-- 'Option' (if it has any).
1452-- 'Option' (if it has any).
1287−finalizeRequest :: MonadIO m => Option scheme -> L.Request -> m L.Request
1453+finalizeRequest :: (MonadIO m) => Option scheme -> L.Request -> m L.Request
1288finalizeRequest (Option _ mfinalizer) = liftIO . fromMaybe pure mfinalizer
1454finalizeRequest (Option _ mfinalizer) = liftIO . fromMaybe pure mfinalizer
1289
1455
1290----------------------------------------------------------------------------
1456----------------------------------------------------------------------------
@@ -1308,7 +1474,7 @@ infix 7 =:
1308(=:) :: (QueryParam param, ToHttpApiData a) => Text -> a -> param
1474(=:) :: (QueryParam param, ToHttpApiData a) => Text -> a -> param
1309name =: value = queryParam name (pure value)
1475name =: value = queryParam name (pure value)
1310
1476
1311−-- | Construct a flag, that is, valueless query parameter. For example, in
1477+-- | Construct a flag, that is, a valueless query parameter. For example, in
1312-- 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
1313-- with a value:
1479-- with a value:
1314--
1480--
@@ -1317,9 +1483,27 @@ name =: value = queryParam name (pure value)
1317-- This operator is defined in terms of 'queryParam':
1483-- This operator is defined in terms of 'queryParam':
1318--
1484--
1319-- > queryFlag name = queryParam name (Nothing :: Maybe ())
1485-- > queryFlag name = queryParam name (Nothing :: Maybe ())
1320−queryFlag :: QueryParam param => Text -> param
1486+queryFlag :: (QueryParam param) => Text -> param
1321queryFlag name = queryParam name (Nothing :: Maybe ())
1487queryFlag name = queryParam name (Nothing :: Maybe ())
1322
1488
1489+-- | Construct query parameters from a 'ToForm' instance. This function
1490+-- produces the same query params as 'Form.urlEncodeAsFormStable'.
1491+--
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@).
1496+--
1497+-- @since 3.11.0
1498+formToQuery :: (QueryParam param, Monoid param, ToForm f) => f -> param
1499+formToQuery f = mconcat . fmap toParam . Form.toListStable $ toForm f
1500+ where
1501+ toParam (key, val) =
1502+ queryParam key $
1503+ if val == ""
1504+ then Nothing
1505+ else Just val
1506+
1323-- | 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
1324-- 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
1325-- 'FormUrlEncodedParam' when constructing form URL encoded request bodies.
1509-- 'FormUrlEncodedParam' when constructing form URL encoded request bodies.
@@ -1329,11 +1513,17 @@ class QueryParam param where
1329 -- '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
1330 -- way). It's recommended to use @('=:')@ and 'queryFlag' instead of this
1514 -- way). It's recommended to use @('=:')@ and 'queryFlag' instead of this
1331 -- method, because they are easier to read.
1515 -- method, because they are easier to read.
1332− queryParam :: ToHttpApiData a => Text -> Maybe a -> param
1516+ queryParam :: (ToHttpApiData a) => Text -> Maybe a -> param
1517+
1518+ -- | Get the query parameter names and values set by 'queryParam'.
1519+ --
1520+ -- @since 3.11.0
1521+ queryParamToList :: param -> [(Text, Maybe Text)]
1333
1522
1334instance QueryParam (Option scheme) where
1523instance QueryParam (Option scheme) where
1335 queryParam name mvalue =
1524 queryParam name mvalue =
1336 withQueryParams ((:) (name, toQueryParam <$> mvalue))
1525 withQueryParams ((:) (name, toQueryParam <$> mvalue))
1526+ queryParamToList (Option f _) = fst $ appEndo f ([], L.defaultRequest)
1337
1527
1338----------------------------------------------------------------------------
1528----------------------------------------------------------------------------
1339-- Request—Optional parameters—Headers
1529-- Request—Optional parameters—Headers
@@ -1357,6 +1547,14 @@ attachHeader :: ByteString -> ByteString -> L.Request -> L.Request
1357attachHeader name value x =
1547attachHeader name value x =
1358 x {L.requestHeaders = (CI.mk name, value) : L.requestHeaders x}
1548 x {L.requestHeaders = (CI.mk name, value) : L.requestHeaders x}
1359
1549
1550+-- | Same as 'header', but with redacted values on print.
1551+--
1552+-- @since 3.13.0
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}
1557+
1360----------------------------------------------------------------------------
1558----------------------------------------------------------------------------
1361-- Request—Optional parameters—Cookies
1559-- Request—Optional parameters—Cookies
1362
1560
@@ -1498,7 +1696,7 @@ customAuth = Option mempty . pure
1498
1696
1499-- | Specify the port to connect to explicitly. Normally, 'Url' you use
1697-- | Specify the port to connect to explicitly. Normally, 'Url' you use
1500-- 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
1501−-- 'Option' allows to choose an arbitrary port overwriting the defaults.
1699+-- 'Option' allows us to choose an arbitrary port overwriting the defaults.
1502port :: Int -> Option scheme
1700port :: Int -> Option scheme
1503port n = withRequest $ \x ->
1701port n = withRequest $ \x ->
1504 x {L.port = n}
1702 x {L.port = n}
@@ -1513,8 +1711,8 @@ port n = withRequest $ \x ->
1513--
1711--
1514-- > decompress (const True)
1712-- > decompress (const True)
1515decompress ::
1713decompress ::
1516− -- | Predicate that is given MIME type, it
1714+ -- | Predicate that is given MIME type, it returns 'True' when content
1517− -- returns 'True' when content should be decompressed on the fly.
1715+ -- should be decompressed on the fly.
1518 (ByteString -> Bool) ->
1716 (ByteString -> Bool) ->
1519 Option scheme
1717 Option scheme
1520decompress f = withRequest $ \x ->
1718decompress f = withRequest $ \x ->
@@ -1564,7 +1762,7 @@ ignoreResponse = Proxy
1564newtype JsonResponse a = JsonResponse (L.Response a)
1762newtype JsonResponse a = JsonResponse (L.Response a)
1565 deriving (Show)
1763 deriving (Show)
1566
1764
1567−instance FromJSON a => HttpResponse (JsonResponse a) where
1765+instance (FromJSON a) => HttpResponse (JsonResponse a) where
1568 type HttpResponseBody (JsonResponse a) = a
1766 type HttpResponseBody (JsonResponse a) = a
1569 toVanillaResponse (JsonResponse r) = r
1767 toVanillaResponse (JsonResponse r) = r
1570 getHttpResponse r = do
1768 getHttpResponse r = do
@@ -1616,7 +1814,7 @@ lbsResponse = Proxy
1616----------------------------------------------------------------------------
1814----------------------------------------------------------------------------
1617-- Helpers for response interpretations
1815-- Helpers for response interpretations
1618
1816
1619−-- | Fetch beginning of response and return it together with new
1817+-- | Fetch beginning of the response and return it together with a new
1620-- @'L.Response' 'L.BodyReader'@ that can be passed to 'getHttpResponse' and
1818-- @'L.Response' 'L.BodyReader'@ that can be passed to 'getHttpResponse' and
1621-- such.
1819-- such.
1622grabPreview ::
1820grabPreview ::
@@ -1680,14 +1878,14 @@ brReadN br n = go 0 id id
1680
1878
1681-- | Get the response body.
1879-- | Get the response body.
1682responseBody ::
1880responseBody ::
1683− HttpResponse response =>
1881+ (HttpResponse response) =>
1684 response ->
1882 response ->
1685 HttpResponseBody response
1883 HttpResponseBody response
1686responseBody = L.responseBody . toVanillaResponse
1884responseBody = L.responseBody . toVanillaResponse
1687
1885
1688-- | Get the response status code.
1886-- | Get the response status code.
1689responseStatusCode ::
1887responseStatusCode ::
1690− HttpResponse response =>
1888+ (HttpResponse response) =>
1691 response ->
1889 response ->
1692 Int
1890 Int
1693responseStatusCode =
1891responseStatusCode =
@@ -1695,7 +1893,7 @@ responseStatusCode =
1695
1893
1696-- | Get the response status message.
1894-- | Get the response status message.
1697responseStatusMessage ::
1895responseStatusMessage ::
1698− HttpResponse response =>
1896+ (HttpResponse response) =>
1699 response ->
1897 response ->
1700 ByteString
1898 ByteString
1701responseStatusMessage =
1899responseStatusMessage =
@@ -1703,7 +1901,7 @@ responseStatusMessage =
1703
1901
1704-- | Lookup a particular header from a response.
1902-- | Lookup a particular header from a response.
1705responseHeader ::
1903responseHeader ::
1706− HttpResponse response =>
1904+ (HttpResponse response) =>
1707 -- | Response interpretation
1905 -- | Response interpretation
1708 response ->
1906 response ->
1709 -- | Header to lookup
1907 -- | Header to lookup
@@ -1715,7 +1913,7 @@ responseHeader r h =
1715
1913
1716-- | Get the response 'L.CookieJar'.
1914-- | Get the response 'L.CookieJar'.
1717responseCookieJar ::
1915responseCookieJar ::
1718− HttpResponse response =>
1916+ (HttpResponse response) =>
1719 response ->
1917 response ->
1720 L.CookieJar
1918 L.CookieJar
1721responseCookieJar = L.responseCookieJar . toVanillaResponse
1919responseCookieJar = L.responseCookieJar . toVanillaResponse
@@ -1728,9 +1926,9 @@ responseCookieJar = L.responseCookieJar . toVanillaResponse
1728-- 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
1729-- type an instance of the 'HttpResponse' type class.
1927-- type an instance of the 'HttpResponse' type class.
1730
1928
1731−-- | 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
1732−-- consume response from a @'L.Response' 'L.BodyReader'@ and produce the
1930+-- to consume the response from a @'L.Response' 'L.BodyReader'@ and produce
1733−-- final result that is to be returned to the user.
1931+-- the final result that is to be returned to the user.
1734class HttpResponse response where
1932class HttpResponse response where
1735 -- | 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
1736 -- instance of 'HttpResponse'.
1934 -- instance of 'HttpResponse'.
@@ -1769,6 +1967,16 @@ class HttpResponse response where
1769 acceptHeader :: Proxy response -> Maybe ByteString
1967 acceptHeader :: Proxy response -> Maybe ByteString
1770 acceptHeader Proxy = Nothing
1968 acceptHeader Proxy = Nothing
1771
1969
1970+-- | This instance has been added to make it easier to inspect 'L.Response'
1971+-- using Req's functions like 'responseStatusCode', 'responseStatusMessage',
1972+-- etc.
1973+--
1974+-- @since 3.12.0
1975+instance HttpResponse (L.Response ()) where
1976+ type HttpResponseBody (L.Response ()) = ()
1977+ toVanillaResponse = id
1978+ getHttpResponse = return . void
1979+
1772----------------------------------------------------------------------------
1980----------------------------------------------------------------------------
1773-- Other
1981-- Other
1774
1982
@@ -1794,7 +2002,7 @@ class RequestComponent a where
1794-- method@ and @'HttpBody' body => 'RequestComponent' body@ when it decides
2002-- method@ and @'HttpBody' body => 'RequestComponent' body@ when it decides
1795-- 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,
1796-- when instance is already chosen).
2004-- when instance is already chosen).
1797−newtype Womb (tag :: Symbol) a = Womb a
2005+newtype Tagged (tag :: Symbol) a = Tagged a
1798
2006
1799-- | Exceptions that this library throws.
2007-- | Exceptions that this library throws.
1800data HttpException
2008data HttpException
@@ -1803,10 +2011,24 @@ data HttpException
1803 | -- | A wrapper with Aeson-produced 'String' describing why decoding
2011 | -- | A wrapper with Aeson-produced 'String' describing why decoding
1804 -- failed
2012 -- failed
1805 JsonHttpException String
2013 JsonHttpException String
1806− deriving (Show, Typeable, Generic)
2014+ deriving (Show, Generic)
1807
2015
1808instance Exception HttpException
2016instance Exception HttpException
1809
2017
2018+-- | Return 'Just' if the given 'HttpException' is wrapping a http-client's
2019+-- 'L.StatusCodeException'. Otherwise, return 'Nothing'.
2020+--
2021+-- @since 3.12.0
2022+isStatusCodeException :: HttpException -> Maybe (L.Response ())
2023+isStatusCodeException
2024+ ( VanillaHttpException
2025+ ( L.HttpExceptionRequest
2026+ _
2027+ (L.StatusCodeException r _)
2028+ )
2029+ ) = Just r
2030+isStatusCodeException _ = Nothing
2031+
1810-- | 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
1811-- 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
1812-- tags.
2034-- tags.
@@ -1826,11 +2048,4 @@ data Scheme
1826 Http
2048 Http
1827 | -- | HTTPS
2049 | -- | HTTPS
1828 Https
2050 Https
1829− deriving (Eq, Ord, Show, Data, Typeable, Generic, TH.Lift)
2051+ deriving (Eq, Ord, Show, Data, Generic, TH.Lift)
1830−
1831−----------------------------------------------------------------------------
1832−-- Constants
1833−
1834−-- | Max length of preview fragment of response body.
1835−bodyPreviewLength :: Num a => a
1836−bodyPreviewLength = 1024
README.md+28−124
@@ -4,10 +4,8 @@
4[![Hackage](https://img.shields.io/hackage/v/req.svg?style=flat)](https://hackage.haskell.org/package/req)
4[![Hackage](https://img.shields.io/hackage/v/req.svg?style=flat)](https://hackage.haskell.org/package/req)
5[![Stackage Nightly](http://stackage.org/package/req/badge/nightly)](http://stackage.org/nightly/package/req)
5[![Stackage Nightly](http://stackage.org/package/req/badge/nightly)](http://stackage.org/nightly/package/req)
6[![Stackage LTS](http://stackage.org/package/req/badge/lts)](http://stackage.org/lts/package/req)
6[![Stackage LTS](http://stackage.org/package/req/badge/lts)](http://stackage.org/lts/package/req)
7−![CI](https://github.com/mrkkrp/req/workflows/CI/badge.svg?branch=master)
7+[![CI](https://github.com/mrkkrp/req/actions/workflows/ci.yaml/badge.svg)](https://github.com/mrkkrp/req/actions/workflows/ci.yaml)
8
8
9−* [Motivation and Req vs other libraries](#motivation-and-req-vs-other-libraries)
10−* [Unsolved problems](#unsolved-problems)
11* [Related packages](#related-packages)
9* [Related packages](#related-packages)
12* [Blog posts](#blog-posts)
10* [Blog posts](#blog-posts)
13* [Contribution](#contribution)
11* [Contribution](#contribution)
@@ -43,49 +41,33 @@ main = runReq defaultHttpConfig $ do
43 liftIO $ print (responseBody r :: Value)
41 liftIO $ print (responseBody r :: Value)
44```
42```
45
43
46−Req is an easy-to-use, type-safe, expandable, high-level HTTP client library
44+Req is an HTTP client library that attempts to be easy-to-use, type-safe,
47−that just works without any fooling around.
45+and expandable.
48−
46+
49−What does the phrase “easy-to-use” mean? It means that the library is
47+“Easy-to-use” means that the library is designed to be beginner-friendly so
50−designed to be beginner-friendly so it's simple to add to your monad stack,
48+it's simple to add to your monad stack, intuitive to work with,
51−intuitive to work with, well-documented, and does not get in your way. Doing
49+well-documented, and does not get in your way. Doing HTTP requests is a
52−HTTP requests is a common task and Haskell library for this should be very
50+common task and a Haskell library for this should be approachable and clear
53−approachable and clear to beginners, thus certain compromises were made. For
51+to beginners, thus certain compromises were made. For example, one cannot
54−example, one cannot currently modify `ManagerSettings` of the default
52+currently modify `ManagerSettings` of the default manager because the
55−manager because the library always uses the same implicit global manager for
53+library always uses the same implicit global manager for simplicity and
56−simplicity and maximal connection sharing. There is a way to use your own
54+maximal connection sharing. There is a way to use your own manager with
57−manager with different settings, but it requires a bit more typing.
55+different settings, but it requires more typing.
58−
56+
59−“Type-safe” means that the library is protective and eliminates certain
57+“Type-safe” means that the library tries to eliminate certain classes of
60−classes of errors. For example, we have correct-by-construction URLs, it's
58+errors. For example, we have correct-by-construction URLs; it is guaranteed
61−guaranteed that the user does not send the request body when using methods
59+that the user does not send the request body when using methods like GET or
62−like GET or OPTIONS, and the amount of implicit assumptions is minimized by
60+OPTIONS, and the amount of implicit assumptions is minimized by making the
63−making the user specify his/her intentions in an explicit form (for example,
61+user specify their intentions in an explicit form. For example, it's not
64−it's not possible to avoid specifying the body or method of request).
62+possible to avoid specifying the body or the method of a request.
65Authentication methods that assume HTTPS force the user to use HTTPS at the
63Authentication methods that assume HTTPS force the user to use HTTPS at the
66−type level. The library also carefully hides underlying types from the
64+type level.
67−lower-level `http-client` package because those types are not safe enough
65+
68−(for example `Request` is an instance of `IsString` and, if it's malformed,
69−it will blow up at run-time).
70−
71−“Expandable” refers to the ability to create new components for dealing with
66+“Expandable” refers to the ability to create new components without having
72−HTTP without having to resort to ugly hacking. For example, it's possible to
67+to resort to hacking. For example, it's possible to define your own HTTP
73−define your own HTTP methods, create new ways to construct the body of a
68+methods, create new ways to construct the body of a request, create new
74−request, create new authorization options, perform a request in a different
69+authorization options, perform a request in a different way, and create your
75−way, and create your own methods to parse and represent a response. As the
70+own methods to parse a response.
76−user extends the library to satisfy his/her special needs, the new solutions
77−will work just like the built-ins. However, all of the common cases are also
78−covered by the library out-of-the-box.
79−
80−“High-level” means that there are less details to worry about. The library
81−is a result of my experiences as a Haskell consultant. Working for several
82−clients, who had very different projects, showed me that the library should
83−adapt easily to any particular style of writing Haskell applications. For
84−example, some people prefer throwing exceptions, while others are concerned
85−with purity. Just define `handleHttpException` accordingly when making your
86−monad instance of `MonadHttp` and it will play together seamlessly. Finally,
87−the library cuts down boilerplate considerably, and helps you write concise,
88−easy to read, and maintainable code.
89
71
90The library uses the following mature packages under the hood to guarantee
72The library uses the following mature packages under the hood to guarantee
91you the best experience:
73you the best experience:
@@ -95,89 +77,11 @@ you the best experience:
95* [`http-client-tls`](https://hackage.haskell.org/package/http-client-tls)—TLS
77* [`http-client-tls`](https://hackage.haskell.org/package/http-client-tls)—TLS
96 (HTTPS) support for `http-client`.
78 (HTTPS) support for `http-client`.
97
79
98−It's important to note that since we leverage well-known libraries that the
80+It is important to note that since we leverage well-known libraries that the
99whole Haskell ecosystem uses, there is no risk in using Req. The machinery
81whole Haskell ecosystem uses, there is no risk in using Req. The machinery
100for performing requests is the same as with `http-conduit` and Wreq. The
82for performing requests is the same as with `http-conduit` and Wreq. The
101only difference is the API.
83only difference is the API.
102
84
103−## Motivation and Req vs other libraries
104−
105−*This section is my opinion and it contains criticisms of other well-known
106−libraries. If you're a user/fan of one of these libraries, please remember
107−not to react aggressively and respect the fact that I may have different
108−views on API design from yours.*
109−
110−I have spent time to write the library because sending HTTP requests is a
111−common need, but there is no high-level library for that in Haskell that I
112−could use with pleasure. I'll explain why.
113−
114−First of all, there is `http-client` and `http-client-tls`. They just work.
115−I have no issues with the libraries except that they are too low-level for
116−my taste. Indeed, even the docs say that they are low-level and “intended as
117−a base layer for more user-friendly packages”. This is exactly how I use
118−them in Req, as base level. Req is nothing but a different API to
119−`http-client`, so it only works because of the hard work put into
120−`http-client`.
121−
122−`http-conduit` definitely has its place. For one thing it allows you to
123−stream request and response bodies in constant memory, what other library
124−allows you to do that? On the other hand if you take a look at
125−`Network.HTTP.Simple`, then although it's said that it's a “higher level
126−API”, it's mostly the same as vanilla `http-client` in spirit/approach and
127−just adds `conduit`-powered functions to perform requests and allows to use
128−global implicit `Manager` (Req does the same). If I tried to frame what
129−exactly I don't like about `http-conduit` in words, then it would be “the
130−way requests are constructed”. You *set* parameters instead of *being
131−forced* to declare necessary bits and *being allowed* to declare optional
132−bits in a way that their combination is valid. Also, with `http-conduit` you
133−parse request from a string without the protection of TH that otherwise
134−saves the day as in Yesod.
135−
136−Then there is Wreq. `wreq` [doesn't see much development
137−lately](https://github.com/bos/wreq/issues/93). `wreq` is by itself a weird
138−library, IMO. You have functions per method—not very good, as there may be
139−new methods, like PATCH which is not new but still missing (well, you have
140−`customMethod`, but what is the point of having per-method functions if you
141−have a more general way to use any method? you should be able to just insert
142−methods in the “argument slot” of `customMethod` and end up with a more
143−general solution). Now, every method function has a companion that takes
144−`Options` (like you have `get` and `getWith`). Why the duplication? Where is
145−generality and flexibility? This is not all though, because you cannot
146−really use `get` you see in the main module, because you want to have
147−connection sharing. Wreq's author does not take the gift of automatic
148−connection re-use `Manager` from `http-client` provides, he invents the
149−whole new thing of “sessions”. Only inside a session your connections will
150−be shared and re-used. However with the session stuff you have yet another
151−set of per-method functions like `get` and `getWith`—these are different
152−ones, to be used with sessions! Now if you have a multi-threaded app, here
153−is a surprise for you: you can't share connections between threads as
154−connections are shared only inside of the `withSession` friend and “session
155−will no longer be valid after that function returns”. There are valid uses
156−for sessions, but the point is that they are just too inconvenient for
157−common tasks.
158−
159−I used `servant-client` a couple of times but the amount of boilerplate it
160−requires is frightening. If you have several query parameters, and you use
161−just one of them, you'll have to pass lots of `Nothing`s.
162−
163−## Unsolved problems
164−
165−AWS request signing is problematic because request body can be in the form
166−of an action to execute (and all that “popper” stuff for streaming), not
167−just a `ByteString` and so getting its digest (hash) is not trivial without
168−running the action and consuming body in its entirety before the request in
169−made. In Wreq the author chose to just use `error` when body is not a
170−(strict or lazy) `ByteString`. Maybe it's OK for Wreq, but I don't consider
171−this a proper solution for Req as we support full variety of body options.
172−For example, what if I want to upload 1 Gb file to S3? I want to stream it
173−in constant memory but at the same time I need to calculate its hash before
174−I start streaming. One solution to the problem seems to be in taking the
175−hash explicitly (as an argument of the hypothetical `awsAuth`) and making it
176−a responsibility of the user to calculate the hash correctly. I don't like
177−this because it's not user-friendly. So the question stays open, for now
178−there is no AWS signing functionality provided out-of-the-box. The best
179−solution for talking to AWS is the `amazonka` package so far.
180−
181## Related packages
85## Related packages
182
86
183The following packages are designed to be used with Req:
87The following packages are designed to be used with Req:
Setup.hsdeleted−6
@@ -1,6 +0,0 @@
1−module Main (main) where
2−
3−import Distribution.Simple
4−
5−main :: IO ()
6−main = defaultMain
cabal.projectnew file+4
@@ -0,0 +1,4 @@
1+packages: .
2+tests: True
3+benchmarks: True
4+constraints: req +dev
httpbin-tests/Network/HTTP/ReqSpec.hs+107−70
@@ -1,6 +1,6 @@
1−{-# LANGUAGE CPP #-}
2{-# LANGUAGE DataKinds #-}
1{-# LANGUAGE DataKinds #-}
3{-# LANGUAGE FlexibleInstances #-}
2{-# LANGUAGE FlexibleInstances #-}
3+{-# LANGUAGE LambdaCase #-}
4{-# LANGUAGE OverloadedStrings #-}
4{-# LANGUAGE OverloadedStrings #-}
5{-# LANGUAGE RankNTypes #-}
5{-# LANGUAGE RankNTypes #-}
6{-# OPTIONS_GHC -fno-warn-orphans #-}
6{-# OPTIONS_GHC -fno-warn-orphans #-}
@@ -8,29 +8,28 @@
8module Network.HTTP.ReqSpec (spec) where
8module Network.HTTP.ReqSpec (spec) where
9
9
10import Control.Exception
10import Control.Exception
11−import Control.Monad.Reader
11+import Control.Monad (forM_)
12import Control.Monad.Trans.Control
12import Control.Monad.Trans.Control
13import Data.Aeson (ToJSON (..), Value (..), object, (.=))
13import Data.Aeson (ToJSON (..), Value (..), object, (.=))
14−import qualified Data.Aeson as A
14+import Data.Aeson qualified as A
15+import Data.Aeson.KeyMap qualified as Aeson.KeyMap
15−import qualified Data.ByteString as B
16+import Data.ByteString qualified as B
16−import qualified Data.ByteString.Lazy as BL
17+import Data.ByteString.Lazy qualified as BL
17−import qualified Data.HashMap.Strict as HM
18+import Data.Functor.Identity (runIdentity)
19+import Data.Maybe (fromJust)
18import Data.Proxy
20import Data.Proxy
19import Data.Text (Text)
21import Data.Text (Text)
20−import qualified Data.Text as T
22+import Data.Text qualified as T
21−import qualified Data.Text.Encoding as T
23+import Data.Text.Encoding qualified as T
22−import qualified Data.Text.IO as TIO
24+import Data.Text.IO qualified as TIO
23−import qualified Network.HTTP.Client as L
25+import Network.HTTP.Client qualified as L
24−import qualified Network.HTTP.Client.MultipartFormData as LM
26+import Network.HTTP.Client.MultipartFormData qualified as LM
25−import Network.HTTP.Req
27+import Network.HTTP.Req hiding (req)
28+import Network.HTTP.Req qualified as Req
26−import qualified Network.HTTP.Types as Y
29+import Network.HTTP.Types qualified as Y
27import Test.Hspec
30import Test.Hspec
28import Test.QuickCheck
31import Test.QuickCheck
29
32
30−#if !MIN_VERSION_base(4,13,0)
31−import Data.Semigroup ((<>))
32−#endif
33−
34spec :: Spec
33spec :: Spec
35spec = do
34spec = do
36 describe "exception throwing on non-2xx status codes" $
35 describe "exception throwing on non-2xx status codes" $
@@ -51,6 +50,11 @@ spec = do
51 blindlyThrowing (req GET httpbin NoReqBody ignoreResponse mempty)
50 blindlyThrowing (req GET httpbin NoReqBody ignoreResponse mempty)
52 `shouldThrow` anyException
51 `shouldThrow` anyException
53
52
53+ describe "isStatusCodeException" $
54+ it "extracts non-2xx response" $
55+ req GET (httpbin /: "foo") NoReqBody ignoreResponse mempty
56+ `shouldThrow` selector404ByStatusCodeException
57+
54 describe "receiving user-agent header back" $
58 describe "receiving user-agent header back" $
55 it "works" $ do
59 it "works" $ do
56 r <-
60 r <-
@@ -81,8 +85,7 @@ spec = do
81 .= object
85 .= object
82 [ "Accept-Encoding" .= ("gzip" :: Text),
86 [ "Accept-Encoding" .= ("gzip" :: Text),
83 "Foo" .= ("bar" :: Text),
87 "Foo" .= ("bar" :: Text),
84− "Baz" .= ("quux" :: Text),
88+ "Baz" .= ("quux" :: Text)
85− "Host" .= ("httpbin.org" :: Text)
86 ]
89 ]
87 ]
90 ]
88 responseStatusCode r `shouldBe` 200
91 responseStatusCode r `shouldBe` 200
@@ -94,11 +97,10 @@ spec = do
94 (stripFunnyHeaders . stripOrigin) (responseBody r)
97 (stripFunnyHeaders . stripOrigin) (responseBody r)
95 `shouldBe` object
98 `shouldBe` object
96 [ "args" .= emptyObject,
99 [ "args" .= emptyObject,
97− "url" .= ("https://httpbin.org/get" :: Text),
100+ "url" .= ("http://localhost:1234/get" :: Text),
98 "headers"
101 "headers"
99 .= object
102 .= object
100− [ "Accept-Encoding" .= ("gzip" :: Text),
103+ [ "Accept-Encoding" .= ("gzip" :: Text)
101− "Host" .= ("httpbin.org" :: Text)
102 ]
104 ]
103 ]
105 ]
104 responseHeader r "Content-Type" `shouldBe` return "application/json"
106 responseHeader r "Content-Type" `shouldBe` return "application/json"
@@ -115,12 +117,11 @@ spec = do
115 [ "args" .= emptyObject,
117 [ "args" .= emptyObject,
116 "json" .= text,
118 "json" .= text,
117 "data" .= reflected,
119 "data" .= reflected,
118− "url" .= ("https://httpbin.org/post" :: Text),
120+ "url" .= ("http://localhost:1234/post" :: Text),
119 "headers"
121 "headers"
120 .= object
122 .= object
121 [ "Content-Type" .= ("application/json; charset=utf-8" :: Text),
123 [ "Content-Type" .= ("application/json; charset=utf-8" :: Text),
122 "Accept-Encoding" .= ("gzip" :: Text),
124 "Accept-Encoding" .= ("gzip" :: Text),
123− "Host" .= ("httpbin.org" :: Text),
124 "Content-Length" .= show (T.length reflected)
125 "Content-Length" .= show (T.length reflected)
125 ],
126 ],
126 "files" .= emptyObject,
127 "files" .= emptyObject,
@@ -138,18 +139,17 @@ spec = do
138 LM.partBS "bar" "bar data!"
139 LM.partBS "bar" "bar data!"
139 ]
140 ]
140 r <- req POST (httpbin /: "post") body jsonResponse mempty
141 r <- req POST (httpbin /: "post") body jsonResponse mempty
141− let Just contentType = getRequestContentType body
142+ let contentType = fromJust (getRequestContentType body)
142 (stripFunnyHeaders . stripOrigin) (responseBody r)
143 (stripFunnyHeaders . stripOrigin) (responseBody r)
143 `shouldBe` object
144 `shouldBe` object
144 [ "args" .= emptyObject,
145 [ "args" .= emptyObject,
145 "json" .= Null,
146 "json" .= Null,
146 "data" .= ("" :: Text),
147 "data" .= ("" :: Text),
147− "url" .= ("https://httpbin.org/post" :: Text),
148+ "url" .= ("http://localhost:1234/post" :: Text),
148 "headers"
149 "headers"
149 .= object
150 .= object
150 [ "Content-Type" .= T.decodeUtf8 contentType,
151 [ "Content-Type" .= T.decodeUtf8 contentType,
151 "Accept-Encoding" .= ("gzip" :: Text),
152 "Accept-Encoding" .= ("gzip" :: Text),
152− "Host" .= ("httpbin.org" :: Text),
153 "Content-Length" .= ("242" :: Text)
153 "Content-Length" .= ("242" :: Text)
154 ],
154 ],
155 "files" .= emptyObject,
155 "files" .= emptyObject,
@@ -174,11 +174,10 @@ spec = do
174 [ "args" .= emptyObject,
174 [ "args" .= emptyObject,
175 "json" .= Null,
175 "json" .= Null,
176 "data" .= contents,
176 "data" .= contents,
177− "url" .= ("https://httpbin.org/patch" :: Text),
177+ "url" .= ("http://localhost:1234/patch" :: Text),
178 "headers"
178 "headers"
179 .= object
179 .= object
180 [ "Accept-Encoding" .= ("gzip" :: Text),
180 [ "Accept-Encoding" .= ("gzip" :: Text),
181− "Host" .= ("httpbin.org" :: Text),
182 "Content-Length" .= show (T.length contents)
181 "Content-Length" .= show (T.length contents)
183 ],
182 ],
184 "files" .= emptyObject,
183 "files" .= emptyObject,
@@ -200,12 +199,11 @@ spec = do
200 [ "args" .= emptyObject,
199 [ "args" .= emptyObject,
201 "json" .= Null,
200 "json" .= Null,
202 "data" .= ("" :: Text),
201 "data" .= ("" :: Text),
203− "url" .= ("https://httpbin.org/put" :: Text),
202+ "url" .= ("http://localhost:1234/put" :: Text),
204 "headers"
203 "headers"
205 .= object
204 .= object
206 [ "Content-Type" .= ("application/x-www-form-urlencoded" :: Text),
205 [ "Content-Type" .= ("application/x-www-form-urlencoded" :: Text),
207 "Accept-Encoding" .= ("gzip" :: Text),
206 "Accept-Encoding" .= ("gzip" :: Text),
208− "Host" .= ("httpbin.org" :: Text),
209 "Content-Length" .= ("18" :: Text)
207 "Content-Length" .= ("18" :: Text)
210 ],
208 ],
211 "files" .= emptyObject,
209 "files" .= emptyObject,
@@ -263,21 +261,17 @@ spec = do
263 -- TODO /response-headers
261 -- TODO /response-headers
264 -- TODO /redirect
262 -- TODO /redirect
265
263
266− -- FIXME Redirects test is temporarily disabled due to
267− --
268− -- https://github.com/postmanlabs/httpbin/issues/617
269−
270− -- describe "redirects" $
264+ describe "redirects" $
271− -- it "follows redirects" $ do
265+ it "follows redirects" $ do
272− -- r <-
266+ r <-
273− -- req
267+ req
274− -- GET
268+ GET
275− -- (httpbin /: "redirect-to")
269+ (httpbin /: "redirect-to")
276− -- NoReqBody
270+ NoReqBody
277− -- ignoreResponse
271+ ignoreResponse
278− -- ("url" =: ("https://httpbin.org" :: Text))
272+ ("url" =: ("https://httpbin.org" :: Text))
279− -- responseStatusCode r `shouldBe` 200
273+ responseStatusCode r `shouldBe` 200
280− -- responseStatusMessage r `shouldBe` "OK"
274+ responseStatusMessage r `shouldBe` "OK"
281
275
282 -- TODO /relative-redicet
276 -- TODO /relative-redicet
283 -- TODO /absolute-redirect
277 -- TODO /absolute-redirect
@@ -307,7 +301,7 @@ spec = do
307 (httpbin /: "basic-auth" /~ user /~ password)
301 (httpbin /: "basic-auth" /~ user /~ password)
308 NoReqBody
302 NoReqBody
309 ignoreResponse
303 ignoreResponse
310− (basicAuth (T.encodeUtf8 user) (T.encodeUtf8 password))
304+ (basicAuthUnsafe (T.encodeUtf8 user) (T.encodeUtf8 password))
311 responseStatusCode r `shouldBe` 200
305 responseStatusCode r `shouldBe` 200
312 responseStatusMessage r `shouldBe` "OK"
306 responseStatusMessage r `shouldBe` "OK"
313
307
@@ -394,44 +388,80 @@ instance MonadHttp IO where
394----------------------------------------------------------------------------
388----------------------------------------------------------------------------
395-- Helpers
389-- Helpers
396
390
397−-- | Run request with such settings that it does not signal error on adverse
391+-- | Run a request with such settings that it does not signal errors.
398−-- response status codes.
399prepareForShit :: Req a -> IO a
392prepareForShit :: Req a -> IO a
400prepareForShit = runReq defaultHttpConfig {httpConfigCheckResponse = noNoise}
393prepareForShit = runReq defaultHttpConfig {httpConfigCheckResponse = noNoise}
401 where
394 where
402 noNoise _ _ _ = Nothing
395 noNoise _ _ _ = Nothing
403
396
404−-- | Run request with such settings that it throws on any response.
397+-- | Run a request with such settings that it throws on any response.
405blindlyThrowing :: Req a -> IO a
398blindlyThrowing :: Req a -> IO a
406blindlyThrowing = runReq defaultHttpConfig {httpConfigCheckResponse = doit}
399blindlyThrowing = runReq defaultHttpConfig {httpConfigCheckResponse = doit}
407 where
400 where
408 doit _ _ = error "Oops!"
401 doit _ _ = error "Oops!"
409
402
410-- | 'Url' representing <https://httpbin.org>.
403-- | 'Url' representing <https://httpbin.org>.
411−httpbin :: Url 'Https
404+httpbin :: Url 'Http
412−httpbin = https "httpbin.org"
405+httpbin = http "localhost"
406+
407+req ::
408+ ( MonadHttp m,
409+ HttpMethod method,
410+ HttpBody body,
411+ HttpResponse response,
412+ HttpBodyAllowed (AllowsBody method) (ProvidesBody body)
413+ ) =>
414+ method ->
415+ Url scheme ->
416+ body ->
417+ Proxy response ->
418+ Option scheme ->
419+ m response
420+req method url body responseProxy options =
421+ Req.req method url body responseProxy (options <> defaultOptions)
422+
423+-- | Options to apply by default.
424+defaultOptions :: Option scheme
425+defaultOptions = port 1234
413
426
414-- | Remove “origin” field from JSON value. Origin may change, we don't want
427-- | Remove “origin” field from JSON value. Origin may change, we don't want
415-- to depend on that.
428-- to depend on that.
416stripOrigin :: Value -> Value
429stripOrigin :: Value -> Value
417−stripOrigin (Object m) = Object (HM.delete "origin" m)
430+stripOrigin (Object m) = Object (Aeson.KeyMap.delete "origin" m)
418stripOrigin value = value
431stripOrigin value = value
419
432
420-- | Remove funny headers that might break the tests.
433-- | Remove funny headers that might break the tests.
421stripFunnyHeaders :: Value -> Value
434stripFunnyHeaders :: Value -> Value
422−stripFunnyHeaders (Object m) =
435+stripFunnyHeaders = \case
423− let f (Object p) = Object $ HM.filterWithKey (\k _ -> k `elem` hs) p
436+ Object m ->
437+ Object
438+ ( runIdentity
439+ ( Aeson.KeyMap.alterF
440+ (pure . fmap stripFunnyHeaders')
441+ "headers"
442+ m
443+ )
444+ )
445+ value -> value
446+
447+-- | Similar to 'stripFunnyHeaders', but acts directly on the argument
448+-- without trying to access its "headers" field.
449+stripFunnyHeaders' :: Value -> Value
450+stripFunnyHeaders' = \case
451+ Object p ->
452+ Object $
453+ Aeson.KeyMap.filterWithKey
454+ (\k _ -> k `elem` whitelistedHeaders)
455+ p
424− f value = value
456+ value -> value
425− hs =
457+ where
458+ whitelistedHeaders =
426− [ "Content-Type",
459+ [ "Content-Type",
427− "Accept-Encoding",
460+ "Accept-Encoding",
428− "Host",
429− "Content-Length",
461+ "Content-Length",
430− "Foo",
462+ "Foo",
431− "Baz"
463+ "Baz"
432− ]
464+ ]
433− in Object (HM.adjust f "headers" m)
434−stripFunnyHeaders value = value
435
465
436-- | This is a complete test case that makes use of <https://httpbin.org> to
466-- | This is a complete test case that makes use of <https://httpbin.org> to
437-- get various response status codes.
467-- get various response status codes.
@@ -461,12 +491,19 @@ selector404
461 L.responseStatus response == Y.status404 && not (B.null chunk)
491 L.responseStatus response == Y.status404 && not (B.null chunk)
462selector404 _ = False
492selector404 _ = False
463
493
494+-- | Same as 'selector404' except that it uses 'isStatusCodeException'.
495+selector404ByStatusCodeException :: HttpException -> Bool
496+selector404ByStatusCodeException e =
497+ case isStatusCodeException e of
498+ Nothing -> False
499+ Just r -> responseStatusCode r == 404
500+
464−-- | Empty JSON 'Object'.
501+-- | The empty JSON 'Object'.
465emptyObject :: Value
502emptyObject :: Value
466−emptyObject = Object HM.empty
503+emptyObject = Object Aeson.KeyMap.empty
467
504
468−-- | Get rendered JSON value as 'Text'.
505+-- | Get a rendered JSON value as 'Text'.
469−reflectJSON :: ToJSON a => a -> Text
506+reflectJSON :: (ToJSON a) => a -> Text
470reflectJSON = T.decodeUtf8 . BL.toStrict . A.encode
507reflectJSON = T.decodeUtf8 . BL.toStrict . A.encode
471
508
472-- | Clarify to the type checker that the inner computation is in the 'IO'
509-- | Clarify to the type checker that the inner computation is in the 'IO'
pure-tests/Network/HTTP/ReqSpec.hs+79−34
@@ -1,4 +1,3 @@
1−{-# LANGUAGE CPP #-}
2{-# LANGUAGE DataKinds #-}
1{-# LANGUAGE DataKinds #-}
3{-# LANGUAGE DeriveGeneric #-}
2{-# LANGUAGE DeriveGeneric #-}
4{-# LANGUAGE FlexibleInstances #-}
3{-# LANGUAGE FlexibleInstances #-}
@@ -14,43 +13,41 @@
14
13
15module Network.HTTP.ReqSpec (spec) where
14module Network.HTTP.ReqSpec (spec) where
16
15
17−import qualified Blaze.ByteString.Builder as BB
16+import Blaze.ByteString.Builder qualified as BB
18import Control.Exception (throwIO)
17import Control.Exception (throwIO)
19import Control.Monad
18import Control.Monad
20import Control.Retry
19import Control.Retry
21import Data.Aeson (ToJSON (..))
20import Data.Aeson (ToJSON (..))
22−import qualified Data.Aeson as A
21+import Data.Aeson qualified as A
23import Data.ByteString (ByteString)
22import Data.ByteString (ByteString)
24−import qualified Data.ByteString as B
23+import Data.ByteString qualified as B
25−import qualified Data.ByteString.Char8 as B8
24+import Data.ByteString.Char8 qualified as B8
26−import qualified Data.ByteString.Lazy as BL
25+import Data.ByteString.Lazy qualified as BL
27−import qualified Data.CaseInsensitive as CI
26+import Data.CaseInsensitive qualified as CI
28import Data.Either (isRight)
27import Data.Either (isRight)
29−import qualified Data.List.NonEmpty as NE
28+import Data.List.NonEmpty qualified as NE
30import Data.Maybe (fromJust, fromMaybe, isJust, isNothing)
29import Data.Maybe (fromJust, fromMaybe, isJust, isNothing)
31import Data.Proxy
30import Data.Proxy
32import Data.Text (Text)
31import Data.Text (Text)
33−import qualified Data.Text as T
32+import Data.Text qualified as T
34−import qualified Data.Text.Encoding as T
33+import Data.Text.Encoding qualified as T
35import Data.Time
34import Data.Time
36import Data.Typeable (Typeable, eqT)
35import Data.Typeable (Typeable, eqT)
36+import GHC.Exts (IsList (..))
37import GHC.Generics
37import GHC.Generics
38−import qualified Language.Haskell.TH as TH
38+import Language.Haskell.TH qualified as TH
39−import qualified Language.Haskell.TH.Quote as TH
39+import Language.Haskell.TH.Quote qualified as TH
40−import qualified Network.HTTP.Client as L
40+import Network.HTTP.Client qualified as L
41import Network.HTTP.Req
41import Network.HTTP.Req
42−import qualified Network.HTTP.Types as Y
42+import Network.HTTP.Types qualified as Y
43−import qualified Network.HTTP.Types.Header as Y
43+import Network.HTTP.Types.Header qualified as Y
44import Test.Hspec
44import Test.Hspec
45import Test.Hspec.Core.Spec (SpecM)
45import Test.Hspec.Core.Spec (SpecM)
46import Test.QuickCheck
46import Test.QuickCheck
47import Text.URI (URI)
47import Text.URI (URI)
48−import qualified Text.URI as URI
48+import Text.URI qualified as URI
49−import qualified Text.URI.QQ as QQ
49+import Text.URI.QQ qualified as QQ
50−
50+import Web.FormUrlEncoded qualified as F
51−#if !MIN_VERSION_base(4,13,0)
52−import Data.Semigroup ((<>))
53−#endif
54
51
55spec :: Spec
52spec :: Spec
56spec = do
53spec = do
@@ -164,11 +161,13 @@ spec = do
164 let uriHttp = uri' {URI.uriScheme = Just [QQ.scheme|http|]}
161 let uriHttp = uri' {URI.uriScheme = Just [QQ.scheme|http|]}
165 uriHttps = uri' {URI.uriScheme = Just [QQ.scheme|https|]}
162 uriHttps = uri' {URI.uriScheme = Just [QQ.scheme|https|]}
166 requestHttp <-
163 requestHttp <-
167− let Left (url', options) = fromJust (useURI uriHttp)
164+ case fromJust (useURI uriHttp) of
168− in req_ GET url' NoReqBody options
165+ Left (url', options) -> req_ GET url' NoReqBody options
166+ _ -> error "(useURI uriHttp) should have returned Left"
169 requestHttps <-
167 requestHttps <-
170− let Right (url', options) = fromJust (useURI uriHttps)
168+ case fromJust (useURI uriHttps) of
171− in req_ GET url' NoReqBody options
169+ Right (url', options) -> req_ GET url' NoReqBody options
170+ _ -> error "(useURI uriHttps) should have returned Right"
172 L.host requestHttp `shouldBe` uriHost uriHttp
171 L.host requestHttp `shouldBe` uriHost uriHttp
173 L.host requestHttps `shouldBe` uriHost uriHttps
172 L.host requestHttps `shouldBe` uriHost uriHttps
174 L.port requestHttp `shouldBe` uriPort 80 uriHttp
173 L.port requestHttp `shouldBe` uriPort 80 uriHttp
@@ -182,6 +181,26 @@ spec = do
182 lookup "Authorization" (L.requestHeaders requestHttps)
181 lookup "Authorization" (L.requestHeaders requestHttps)
183 `shouldBe` uriBasicAuth uriHttps
182 `shouldBe` uriBasicAuth uriHttps
184
183
184+ describe "renderUrl" $ do
185+ context "http" $ do
186+ context "empty path" $
187+ it "renders correctly" $ do
188+ let (uriHttp, _) = [urlQ|http://httpbin.org|]
189+ renderUrl uriHttp `shouldBe` "http://httpbin.org"
190+ context "non-empty path" $
191+ it "renders correctly" $ do
192+ let (uriHttp, _) = [urlQ|http://httpbin.org/here/we/go|]
193+ renderUrl uriHttp `shouldBe` "http://httpbin.org/here/we/go"
194+ context "http" $ do
195+ context "empty path" $
196+ it "renders correctly" $ do
197+ let (uriHttp, _) = [urlQ|https://httpbin.org|]
198+ renderUrl uriHttp `shouldBe` "https://httpbin.org"
199+ context "non-empty path" $
200+ it "renders correctly" $ do
201+ let (uriHttp, _) = [urlQ|https://httpbin.org/here/we/go|]
202+ renderUrl uriHttp `shouldBe` "https://httpbin.org/here/we/go"
203+
185 describe "bodies" $ do
204 describe "bodies" $ do
186 describe "NoReqBody" $
205 describe "NoReqBody" $
187 it "sets body to empty byte string" $ do
206 it "sets body to empty byte string" $ do
@@ -218,6 +237,19 @@ spec = do
218 L.RequestBodyLBS x -> x `shouldBe` renderQuery params
237 L.RequestBodyLBS x -> x `shouldBe` renderQuery params
219 _ -> expectationFailure "Wrong request body constructor."
238 _ -> expectationFailure "Wrong request body constructor."
220
239
240+ describe "query params" $ do
241+ describe "FormUrlEncodedParam" $ do
242+ describe "formToQuery" $ do
243+ it "should produce the same parameters as F.urlEncodeFormStable" $
244+ property $ \form -> do
245+ request <- req_ POST url (ReqBodyUrlEnc $ formToQuery form) mempty
246+ case L.requestBody request of
247+ L.RequestBodyLBS x -> x `shouldBe` F.urlEncodeFormStable form
248+ _ -> expectationFailure "Wrong request body constructor"
249+ specParamToList (Proxy :: Proxy FormUrlEncodedParam)
250+ describe "Option" $ do
251+ specParamToList (Proxy :: Proxy (Option 'Http))
252+
221 describe "optional parameters" $ do
253 describe "optional parameters" $ do
222 describe "header" $ do
254 describe "header" $ do
223 it "sets specified header value" $
255 it "sets specified header value" $
@@ -246,11 +278,7 @@ spec = do
246 it "cookie jar is set without modifications" $
278 it "cookie jar is set without modifications" $
247 property $ \cjar -> do
279 property $ \cjar -> do
248 request <- req_ GET url NoReqBody (cookieJar cjar)
280 request <- req_ GET url NoReqBody (cookieJar cjar)
249−#if MIN_VERSION_http_client(0,7,0)
250 L.cookieJar request `shouldSatisfy` (maybe False (L.equalCookieJar cjar))
281 L.cookieJar request `shouldSatisfy` (maybe False (L.equalCookieJar cjar))
251−#else
252− L.cookieJar request `shouldBe` Just cjar
253−#endif
254 describe "basicAuth" $ do
282 describe "basicAuth" $ do
255 it "sets Authorization header to correct value" $
283 it "sets Authorization header to correct value" $
256 property $ \username password -> do
284 property $ \username password -> do
@@ -385,7 +413,7 @@ spec = do
385 -- 'Https, Option _) type checks, so we can catch if the type of scheme
413 -- 'Https, Option _) type checks, so we can catch if the type of scheme
386 -- is unspecified.
414 -- is unspecified.
387 let testTypeOfQuoterResult ::
415 let testTypeOfQuoterResult ::
388− forall a s. Typeable a => (a, Option s) -> Bool
416+ forall a s. (Typeable a) => (a, Option s) -> Bool
389 testTypeOfQuoterResult _ = isJust $ eqT @a @(Url 'Https)
417 testTypeOfQuoterResult _ = isJust $ eqT @a @(Url 'Https)
390 in property $ testTypeOfQuoterResult [urlQ|https://example.org/|]
418 in property $ testTypeOfQuoterResult [urlQ|https://example.org/|]
391 it "doesn't work for invalid urls" $
419 it "doesn't work for invalid urls" $
@@ -407,6 +435,7 @@ instance Arbitrary HttpConfig where
407 httpConfigRetryPolicy = retryPolicyDefault
435 httpConfigRetryPolicy = retryPolicyDefault
408 httpConfigRetryJudge _ _ = False
436 httpConfigRetryJudge _ _ = False
409 httpConfigRetryJudgeException _ _ = False
437 httpConfigRetryJudgeException _ _ = False
438+ httpConfigBodyPreviewLength = 1024
410 return HttpConfig {..}
439 return HttpConfig {..}
411
440
412instance Show HttpConfig where
441instance Show HttpConfig where
@@ -474,6 +503,9 @@ instance Arbitrary Day where
474instance Arbitrary DiffTime where
503instance Arbitrary DiffTime where
475 arbitrary = secondsToDiffTime <$> arbitrary
504 arbitrary = secondsToDiffTime <$> arbitrary
476
505
506+instance Arbitrary F.Form where
507+ arbitrary = (F.Form . fromList) <$> arbitrary
508+
477----------------------------------------------------------------------------
509----------------------------------------------------------------------------
478-- Helper types
510-- Helper types
479
511
@@ -541,13 +573,14 @@ uriPort def uri =
541 maybe def (fromIntegral) $
573 maybe def (fromIntegral) $
542 either (const Nothing) Just (URI.uriAuthority uri) >>= URI.authPort
574 either (const Nothing) Just (URI.uriAuthority uri) >>= URI.authPort
543
575
544−-- | Get path from 'URI'.
576+-- | Get the path from a 'URI'.
545uriPath :: URI -> ByteString
577uriPath :: URI -> ByteString
546uriPath uri = fromMaybe "" $ do
578uriPath uri = fromMaybe "" $ do
547− (_, xs) <- URI.uriPath uri
579+ (trailingSlash, xs) <- URI.uriPath uri
548− (return . encodePathPieces . fmap URI.unRText . NE.toList) xs
580+ let pref = (encodePathPieces . fmap URI.unRText . NE.toList) xs
581+ return $ if trailingSlash then pref <> "/" else pref
549
582
550−-- | Get query string from 'URI'.
583+-- | Get the query string from a 'URI'.
551uriQuery :: URI -> ByteString
584uriQuery :: URI -> ByteString
552uriQuery uri = do
585uriQuery uri = do
553 let liftQueryParam = \case
586 let liftQueryParam = \case
@@ -585,3 +618,15 @@ basicProxyAuthHeader :: ByteString -> ByteString -> ByteString
585basicProxyAuthHeader username password =
618basicProxyAuthHeader username password =
586 fromJust . lookup Y.hProxyAuthorization . L.requestHeaders $
619 fromJust . lookup Y.hProxyAuthorization . L.requestHeaders $
587 L.applyBasicProxyAuth username password L.defaultRequest
620 L.applyBasicProxyAuth username password L.defaultRequest
621+
622+-- | Spec about 'paramToList' for the type @p@.
623+specParamToList :: (QueryParam p, Monoid p) => Proxy p -> Spec
624+specParamToList typeProxy = do
625+ describe "paramToList" $ do
626+ it "should reproduce the parameters given by queryParam" $
627+ property $ \(QueryParams params) -> do
628+ let queryParam0 =
629+ (mconcat $ fmap (uncurry queryParam) params)
630+ `asProxyTypeOf` typeProxy
631+ got = queryParamToList queryParam0
632+ got `shouldBe` params
req.cabal+67−70
@@ -1,19 +1,15 @@
1−cabal-version: 1.18
1+cabal-version: 2.4
2name: req
2name: req
3−version: 3.3.0
3+version: 3.13.4
4−license: BSD3
4+license: BSD-3-Clause
5license-file: LICENSE.md
5license-file: LICENSE.md
6maintainer: Mark Karpov <markkarpov92@gmail.com>
6maintainer: Mark Karpov <markkarpov92@gmail.com>
7author: Mark Karpov <markkarpov92@gmail.com>
7author: Mark Karpov <markkarpov92@gmail.com>
8−tested-with: ghc ==8.6.5 ghc ==8.8.3 ghc ==8.10.1
8+tested-with: ghc ==9.6.3 ghc ==9.8.2 ghc ==9.10.1
9homepage: https://github.com/mrkkrp/req
9homepage: https://github.com/mrkkrp/req
10bug-reports: https://github.com/mrkkrp/req/issues
10bug-reports: https://github.com/mrkkrp/req/issues
11−synopsis:
11+synopsis: HTTP client library
12− Easy-to-use, type-safe, expandable, high-level HTTP client library
13−
14−description:
12+description: HTTP client library.
15− Easy-to-use, type-safe, expandable, high-level HTTP client library.
16−
17category: Network, Web
13category: Network, Web
18build-type: Simple
14build-type: Simple
19data-files:
15data-files:
@@ -35,96 +31,97 @@ flag dev
35
31
36library
32library
37 exposed-modules: Network.HTTP.Req
33 exposed-modules: Network.HTTP.Req
38− default-language: Haskell2010
34+ default-language: GHC2021
39 build-depends:
35 build-depends:
40− aeson >=0.9 && <1.6,
36+ aeson >=0.9 && <3,
41− authenticate-oauth >=1.5 && <1.7,
37+ authenticate-oauth >=1.5 && <1.8,
42− base >=4.12 && <5.0,
38+ base >=4.15 && <5,
43 blaze-builder >=0.3 && <0.5,
39 blaze-builder >=0.3 && <0.5,
44− bytestring >=0.10.8 && <0.11,
40+ bytestring >=0.10.8 && <0.13,
45 case-insensitive >=0.2 && <1.3,
41 case-insensitive >=0.2 && <1.3,
42+ containers >=0.5 && <0.8,
46− connection >=0.2.2 && <0.4,
43+ crypton-connection >=0.4.2 && <0.5,
44+ data-default-class >=0.2.0.0,
47 exceptions >=0.6 && <0.11,
45 exceptions >=0.6 && <0.11,
48− http-api-data >=0.2 && <0.5,
46+ http-api-data >=0.2 && <0.7,
49− http-client >=0.5 && <0.8,
47+ http-client >=0.7.13.1 && <0.8,
50 http-client-tls >=0.3.2 && <0.4,
48 http-client-tls >=0.3.2 && <0.4,
51− http-types >=0.8 && <10.0,
49+ http-types >=0.8 && <10,
52 modern-uri >=0.3 && <0.4,
50 modern-uri >=0.3 && <0.4,
53 monad-control >=1.0 && <1.1,
51 monad-control >=1.0 && <1.1,
54 mtl >=2.0 && <3.0,
52 mtl >=2.0 && <3.0,
55− retry >=0.8 && <0.9,
53+ retry >=0.8 && <0.10,
56− template-haskell >=2.14 && <2.17,
54+ template-haskell >=2.19 && <2.23,
57− text >=0.2 && <1.3,
55+ text >=0.2 && <2.2,
58− time >=1.2 && <1.10,
59− transformers >=0.4 && <0.6,
56+ transformers >=0.5.3.0 && <0.7,
60− transformers-base -any
57+ transformers-base,
58+ unliftio-core >=0.1.1 && <0.3
61
59
62 if flag(dev)
60 if flag(dev)
63− ghc-options: -O0 -Wall -Werror
61+ ghc-options:
62+ -Wall -Werror -Wpartial-fields -Wunused-packages
63+ -Wno-unused-imports
64
64
65 else
65 else
66 ghc-options: -O2 -Wall
66 ghc-options: -O2 -Wall
67
67
68− if flag(dev)
69− ghc-options:
70− -Wcompat -Wincomplete-record-updates -Wincomplete-uni-patterns
71− -Wnoncanonical-monad-instances
72−
73test-suite pure-tests
68test-suite pure-tests
74− type: exitcode-stdio-1.0
69+ type: exitcode-stdio-1.0
75− main-is: Spec.hs
70+ main-is: Spec.hs
76− build-tools: hspec-discover >=2.0 && <3.0
71+ build-tool-depends: hspec-discover:hspec-discover >=2 && <3
77− hs-source-dirs: pure-tests
72+ hs-source-dirs: pure-tests
78− other-modules: Network.HTTP.ReqSpec
73+ other-modules: Network.HTTP.ReqSpec
79− default-language: Haskell2010
74+ default-language: GHC2021
80 build-depends:
75 build-depends:
81− QuickCheck >=2.7 && <3.0,
76+ QuickCheck >=2.7 && <3,
82− aeson >=0.9 && <1.6,
77+ aeson >=0.9 && <3,
83− base >=4.12 && <5.0,
78+ base >=4.15 && <5.0,
84 blaze-builder >=0.3 && <0.5,
79 blaze-builder >=0.3 && <0.5,
85− bytestring >=0.10.8 && <0.11,
80+ bytestring >=0.10.8 && <0.13,
86 case-insensitive >=0.2 && <1.3,
81 case-insensitive >=0.2 && <1.3,
87− hspec >=2.0 && <3.0,
82+ hspec >=2.0 && <3,
88− hspec-core >=2.0 && <3.0,
83+ hspec-core >=2.0 && <3,
84+ http-api-data >=0.2 && <0.7,
89− http-client >=0.5 && <0.8,
85+ http-client >=0.7 && <0.8,
90− http-types >=0.8 && <10.0,
86+ http-types >=0.8 && <10,
91 modern-uri >=0.3 && <0.4,
87 modern-uri >=0.3 && <0.4,
92− mtl >=2.0 && <3.0,
93− req -any,
88+ req,
94− retry >=0.8 && <0.9,
89+ retry >=0.8 && <0.10,
95− template-haskell >=2.14 && <2.17,
90+ template-haskell >=2.19 && <2.23,
96− text >=0.2 && <1.3,
91+ text >=0.2 && <2.2,
97− time >=1.2 && <1.10
92+ time >=1.2 && <1.15
98
93
99 if flag(dev)
94 if flag(dev)
100− ghc-options: -O0 -Wall -Werror
95+ ghc-options:
96+ -Wall -Werror -Wredundant-constraints -Wpartial-fields
97+ -Wunused-packages
101
98
102 else
99 else
103 ghc-options: -O2 -Wall
100 ghc-options: -O2 -Wall
104
101
105test-suite httpbin-tests
102test-suite httpbin-tests
106− type: exitcode-stdio-1.0
103+ type: exitcode-stdio-1.0
107− main-is: Spec.hs
104+ main-is: Spec.hs
108− build-tools: hspec-discover >=2.0 && <3.0
105+ build-tool-depends: hspec-discover:hspec-discover >=2 && <3
109− hs-source-dirs: httpbin-tests
106+ hs-source-dirs: httpbin-tests
110− other-modules: Network.HTTP.ReqSpec
107+ other-modules: Network.HTTP.ReqSpec
111− default-language: Haskell2010
108+ default-language: GHC2021
112 build-depends:
109 build-depends:
113− QuickCheck >=2.7 && <3.0,
110+ QuickCheck >=2.7 && <3,
114− aeson >=0.9 && <1.6,
111+ aeson >=2 && <3,
115− base >=4.12 && <5.0,
112+ base >=4.15 && <5,
116− bytestring >=0.10.8 && <0.11,
113+ bytestring >=0.10.8 && <0.13,
117 hspec >=2.0 && <3.0,
114 hspec >=2.0 && <3.0,
118− http-client >=0.5 && <0.8,
115+ http-client >=0.7 && <0.8,
119− http-types >=0.8 && <10.0,
116+ http-types >=0.8 && <10,
120 monad-control >=1.0 && <1.1,
117 monad-control >=1.0 && <1.1,
121− mtl >=2.0 && <3.0,
122− req -any,
118+ req,
123− text >=0.2 && <1.3,
119+ text >=0.2 && <2.2
124− unordered-containers >=0.2.5 && <0.2.12
125
120
126 if flag(dev)
121 if flag(dev)
127− ghc-options: -O0 -Wall -Werror
122+ ghc-options:
123+ -Wall -Werror -Wredundant-constraints -Wpartial-fields
124+ -Wunused-packages
128
125
129 else
126 else
130− ghc-options: -O2 -Wall
127+ buildable: False