http-client 0.4.22 → 0.4.22.1

raw patch · 2 files changed

+69/−25 lines, 2 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• Network/HTTP/Client.hs +68/−24
• http-client.cabal +1/−1

@@ -10,57 +10,57 @@ -- http-client-tls provide secure connections. -- -- There are three core components to be understood here: requests, responses,--- and managers. A @Manager@ keeps track of open connections to various hosts,+-- and managers. A 'Manager' keeps track of open connections to various hosts, -- and when requested, will provide either an existing open connection or--- create a new connection on demand. A @Manager@ also automatically reaps--- connections which have been unused for a certain period of time. A @Manager@+-- create a new connection on demand. A 'Manager' also automatically reaps+-- connections which have been unused for a certain period of time. A 'Manager' -- allows for more efficient HTTP usage by allowing for keep-alive connections. -- Secure HTTP connections can be allowed by modifying the settings used for--- creating a manager. The simplest way to create a @Manager@ is with:+-- creating a manager. The simplest way to create a 'Manager' is with: -- -- @ -- 'newManager' 'defaultManagerSettings' -- @ ----- While generally speaking it is a good idea to share a single @Manager@+-- While generally speaking it is a good idea to share a single 'Manager' -- throughout your application, there are cases where it makes more sense to--- create and destroy @Manager@s more frequently. As an example, if you have an+-- create and destroy 'Manager's more frequently. As an example, if you have an -- application which will make a large number of requests to different hosts, -- and will never make more than one connection to a single host, then sharing--- a @Manager@ will result in idle connections being kept open longer than--- necessary. In such a situation, it makes sense to use @withManager@ around+-- a 'Manager' will result in idle connections being kept open longer than+-- necessary. In such a situation, it makes sense to use 'withManager' around -- each new request, to avoid running out of file descriptors. (Note that the -- 'managerIdleConnectionCount' setting mitigates the risk of leaking too many -- file descriptors.) ----- The next core component is a @Request@, which represents a single HTTP--- request to be sent to a specific server. @Request@s allow for many settings+-- The next core component is a 'Request', which represents a single HTTP+-- request to be sent to a specific server. 'Request's allow for many settings -- to control exact how they function, but usually the simplest approach for--- creating a @Request@ is to use 'parseUrl'.+-- creating a 'Request' is to use 'parseUrl'. ----- Finally, a @Response@ is the result of sending a single @Request@ to a--- server, over a connection which was acquired from a @Manager@. Note that you+-- Finally, a 'Response' is the result of sending a single 'Request' to a+-- server, over a connection which was acquired from a 'Manager'. Note that you -- must close the response when you're done with it to ensure that the--- connection is recycled to the @Manager@ to either be used by another--- request, or to be reaped. Usage of @withResponse@ will ensure that this+-- connection is recycled to the 'Manager' to either be used by another+-- request, or to be reaped. Usage of 'withResponse' will ensure that this -- happens automatically. -- -- Helper packages may provide replacements for various recommendations listed -- above. For example, if using http-client-tls, instead of using--- 'defaultManagerSettings', you would want to use @tlsManagerSettings@. Be+-- 'defaultManagerSettings', you would want to use 'tlsManagerSettings'. Be -- sure to read the relevant helper library documentation for more information. -- -- A note on exceptions: for the most part, all actions that perform I/O should--- be assumed to throw an @HttpException@ in the event of some problem, and all--- pure functions will be total. For example, @withResponse@, @httpLbs@, and--- @BodyReader@ can all throw exceptions. Functions like @responseStatus@ and--- @applyBasicAuth@ are guaranteed to be total (or there\'s a bug in the+-- be assumed to throw an 'HttpException' in the event of some problem, and all+-- pure functions will be total. For example, 'withResponse', 'httpLbs', and+-- 'BodyReader' can all throw exceptions. Functions like 'responseStatus' and+-- 'applyBasicAuth' are guaranteed to be total (or there\'s a bug in the -- library). ----- One thing to be cautioned about: the type of @parseUrl@ allows it to work in--- different monads. If used in the @IO@ monad, it will throw an exception in+-- One thing to be cautioned about: the type of 'parseUrl' allows it to work in+-- different monads. If used in the 'IO' monad, it will throw an exception in -- the case of an invalid URI. In addition, if you leverage the @IsString@--- instance of the @Request@ value via @OverloadedStrings@, an invalid URI will+-- instance of the 'Request' value via @OverloadedStrings@, an invalid URI will -- result in a partial value. Caveat emptor! -- -- Non-2xx responses: the default behavior of all functions in http-client is@@ -69,7 +69,9 @@ -- are not in the 2xx range. These behaviors can be overridden by the -- 'redirectCount' and 'checkStatus' settings on a request, respectively. module Network.HTTP.Client-    ( -- * Performing requests+    ( -- $example1++      -- * Performing requests       withResponse     , httpLbs     , httpNoBody@@ -265,3 +267,45 @@ -- Since 0.4.7 managerSetProxy :: ProxyOverride -> ManagerSettings -> ManagerSettings managerSetProxy po = managerSetInsecureProxy po . managerSetSecureProxy po++++-- $example1+-- = Example Usage+--+-- === Making a GET request+--+-- > import Network.HTTP.Client+-- > import Network.HTTP.Types.Status (statusCode)+-- >+-- > main :: IO ()+-- > main = do+-- >   manager <- newManager defaultManagerSettings+-- >+-- >   request <- parseUrl "http://httpbin.org/post"+-- >   response <- httpLbs request manager+-- >+-- >   putStrLn $ "The status code was: " ++ (show $ statusCode $ responseStatus response)+-- >   print $ responseBody response+--+--+-- === Posting JSON to a server+--+-- > {-# LANGUAGE OverloadedStrings #-}+-- > import Network.HTTP.Client+-- > import Network.HTTP.Types.Status (statusCode)+-- > import Data.Aeson (object, (.=), encode)+-- >+-- > main :: IO ()+-- > main = do+-- >   manager <- newManager defaultManagerSettings+-- >+-- >   -- Create the request+-- >   let requestObject = object ["name" .= "Michael", "age" .= 30]+-- >   initialRequest <- parseUrl "http://httpbin.org/post"+-- >   let request = initialRequest { method = "POST", requestBody = RequestBodyLBS $ encode requestObject }+-- >+-- >   response <- httpLbs request manager+-- >   putStrLn $ "The status code was: " ++ (show $ statusCode $ responseStatus response)+-- >   print $ responseBody response+--

@@ -1,5 +1,5 @@ name:                http-client-version:             0.4.22+version:             0.4.22.1 synopsis:            An HTTP client engine, intended as a base layer for more user-friendly packages. description:         Hackage documentation generation is not reliable. For up to date documentation, please see: <http://www.stackage.org/package/http-client>. homepage:            https://github.com/snoyberg/http-client