Safe Haskell | Safe-Inferred |
---|---|
Language | GHC2021 |
Synopsis
- httpJSON :: (MonadIO m, FromJSON a) => Request -> m (Response a)
- httpLbs :: MonadIO m => Request -> m (Response LByteString)
- httpNoBody :: MonadIO m => Request -> m (Response ())
- httpSink :: MonadUnliftIO m => Request -> (Response () -> ConduitM ByteString Void m a) -> m a
- withResponse :: (MonadUnliftIO m, MonadIO n) => Request -> (Response (ConduitM i ByteString n ()) -> m a) -> m a
- setRequestCheckStatus :: Request -> Request
- setRequestMethod :: ByteString -> Request -> Request
- setRequestHeader :: HeaderName -> [ByteString] -> Request -> Request
- setRequestHeaders :: RequestHeaders -> Request -> Request
- addRequestHeader :: HeaderName -> ByteString -> Request -> Request
- setRequestBody :: RequestBody -> Request -> Request
- getResponseHeaders :: Response a -> [(HeaderName, ByteString)]
- getResponseBody :: Response a -> a
- getResponseStatusCode :: Response a -> Int
- parseRequest :: MonadThrow m => String -> m Request
- getUri :: Request -> URI
- path :: Request -> ByteString
- checkResponse :: Request -> Request -> Response BodyReader -> IO ()
- parseUrlThrow :: MonadThrow m => String -> m Request
- requestHeaders :: Request -> RequestHeaders
- getGlobalManager :: IO Manager
- applyDigestAuth :: (MonadIO m, MonadThrow n) => ByteString -> ByteString -> Request -> Manager -> m (n Request)
- displayDigestAuthException :: DigestAuthException -> String
- data Request
- data RequestBody
- data Response body
- data HttpException
- data HttpExceptionContent
- = StatusCodeException (Response ()) ByteString
- | TooManyRedirects [Response ByteString]
- | OverlongHeaders
- | ResponseTimeout
- | ConnectionTimeout
- | ConnectionFailure SomeException
- | InvalidStatusLine ByteString
- | InvalidHeader ByteString
- | InvalidRequestHeader ByteString
- | InternalException SomeException
- | ProxyConnectException ByteString Int Status
- | NoResponseDataReceived
- | TlsNotSupported
- | WrongRequestBodyStreamSize Word64 Word64
- | ResponseBodyTooShort Word64 Word64
- | InvalidChunkHeaders
- | IncompleteHeaders
- | InvalidDestinationHost ByteString
- | HttpZlibException ZlibException
- | InvalidProxyEnvironmentVariable Text Text
- | ConnectionClosed
- | InvalidProxySettings Text
- notFound404 :: Status
- hAccept :: HeaderName
- hContentLength :: HeaderName
- hContentMD5 :: HeaderName
- method :: Request -> Method
- methodPost :: Method
- methodPut :: Method
- formDataBody :: MonadIO m => [Part] -> Request -> m Request
- partFileRequestBody :: forall (m :: Type -> Type). Applicative m => Text -> FilePath -> RequestBody -> PartM m
- partBS :: forall (m :: Type -> Type). Applicative m => Text -> ByteString -> PartM m
- partLBS :: forall (m :: Type -> Type). Applicative m => Text -> ByteString -> PartM m
- setGitHubHeaders :: Request -> Request
- download :: HasTerm env => Request -> Path Abs File -> RIO env Bool
- redownload :: HasTerm env => Request -> Path Abs File -> RIO env Bool
- verifiedDownload :: HasTerm env => DownloadRequest -> Path Abs File -> (Maybe Integer -> ConduitM ByteString Void (RIO env) ()) -> RIO env Bool
- verifiedDownloadWithProgress :: HasTerm env => DownloadRequest -> Path Abs File -> Text -> Maybe Int -> RIO env Bool
- data CheckHexDigest
- data DownloadRequest
- drRetryPolicyDefault :: RetryPolicy
- data VerifiedDownloadException
- data HashCheck = (Show a, HashAlgorithm a) => HashCheck {}
- mkDownloadRequest :: Request -> DownloadRequest
- setHashChecks :: [HashCheck] -> DownloadRequest -> DownloadRequest
- setLengthCheck :: Maybe LengthCheck -> DownloadRequest -> DownloadRequest
- setRetryPolicy :: RetryPolicy -> DownloadRequest -> DownloadRequest
- setForceDownload :: Bool -> DownloadRequest -> DownloadRequest
Documentation
httpSink :: MonadUnliftIO m => Request -> (Response () -> ConduitM ByteString Void m a) -> m a Source #
withResponse :: (MonadUnliftIO m, MonadIO n) => Request -> (Response (ConduitM i ByteString n ()) -> m a) -> m a Source #
setRequestCheckStatus :: Request -> Request #
Modify the request so that non-2XX status codes generate a runtime
StatusCodeException
, by using throwErrorStatusCodes
Since: http-client-0.5.13
setRequestMethod :: ByteString -> Request -> Request #
Set the request method
Since: http-conduit-2.1.10
setRequestHeader :: HeaderName -> [ByteString] -> Request -> Request #
Set the given request header to the given list of values. Removes any previously set header values with the same name.
Since: http-conduit-2.1.10
setRequestHeaders :: RequestHeaders -> Request -> Request #
Set the request headers, wiping out all previously set headers. This
means if you use setRequestHeaders
to set some headers and also use one of
the other setters that modifies the content-type
header (such as
setRequestBodyJSON
), be sure that setRequestHeaders
is evaluated
first.
Since: http-conduit-2.1.10
addRequestHeader :: HeaderName -> ByteString -> Request -> Request #
Add a request header name/value combination
Since: http-conduit-2.1.10
setRequestBody :: RequestBody -> Request -> Request #
Set the request body to the given RequestBody
. You may want to
consider using one of the convenience functions in the modules, e.g.
requestBodyJSON
.
Note: This will not modify the request method. For that, please use
requestMethod
. You likely don't want the default of GET
.
Since: http-conduit-2.1.10
getResponseHeaders :: Response a -> [(HeaderName, ByteString)] #
Get all response headers
Since: http-conduit-2.1.10
getResponseBody :: Response a -> a #
Get the response body
Since: http-conduit-2.1.10
getResponseStatusCode :: Response a -> Int #
Get the integral status code of the response
Since: http-conduit-2.1.10
parseRequest :: MonadThrow m => String -> m Request #
Convert a URL into a Request
.
This function defaults some of the values in Request
, such as setting method
to
GET
and requestHeaders
to []
.
Since this function uses MonadThrow
, the return monad can be anything that is
an instance of MonadThrow
, such as IO
or Maybe
.
You can place the request method at the beginning of the URL separated by a space, e.g.:
parseRequest "POST http://httpbin.org/post"
Note that the request method must be provided as all capital letters.
A Request
created by this function won't cause exceptions on non-2XX
response status codes.
To create a request which throws on non-2XX status codes, see parseUrlThrow
Since: http-client-0.4.30
path :: Request -> ByteString #
Everything from the host to the query string.
Since 0.1.0
checkResponse :: Request -> Request -> Response BodyReader -> IO () #
Check the response immediately after receiving the status and headers. This can be useful for throwing exceptions on non-success status codes.
In previous versions of http-client, this went under the name
checkStatus
, but was renamed to avoid confusion about the new default
behavior (doing nothing).
Since: http-client-0.5.0
parseUrlThrow :: MonadThrow m => String -> m Request #
Same as parseRequest
, except will throw an HttpException
in the
event of a non-2XX response. This uses throwErrorStatusCodes
to
implement checkResponse
.
Since: http-client-0.4.30
requestHeaders :: Request -> RequestHeaders #
Custom HTTP request headers
The Content-Length and Transfer-Encoding headers are set automatically
by this module, and shall not be added to requestHeaders
.
If not provided by the user, Host
will automatically be set based on
the host
and port
fields.
Moreover, the Accept-Encoding header is set implicitly to gzip for
convenience by default. This behaviour can be overridden if needed, by
setting the header explicitly to a different value. In order to omit the
Accept-Header altogether, set it to the empty string "". If you need an
empty Accept-Header (i.e. requesting the identity encoding), set it to a
non-empty white-space string, e.g. " ". See RFC 2616 section 14.3 for
details about the semantics of the Accept-Header field. If you request a
content-encoding not supported by this module, you will have to decode
it yourself (see also the decompress
field).
Note: Multiple header fields with the same field-name will result in multiple header fields being sent and therefore it's the responsibility of the client code to ensure that the rules from RFC 2616 section 4.2 are honoured.
Since 0.1.0
getGlobalManager :: IO Manager #
Get the current global Manager
Since: http-client-tls-0.2.4
:: (MonadIO m, MonadThrow n) | |
=> ByteString | username |
-> ByteString | password |
-> Request | |
-> Manager | |
-> m (n Request) |
Apply digest authentication to this request.
Note that this function will need to make an HTTP request to the
server in order to get the nonce, thus the need for a Manager
and
to live in IO
. This also means that the request body will be sent
to the server. If the request body in the supplied Request
can
only be read once, you should replace it with a dummy value.
In the event of successfully generating a digest, this will return
a Just
value. If there is any problem with generating the digest,
it will return Nothing
.
Since: http-client-tls-0.3.1
displayDigestAuthException :: DigestAuthException -> String #
User friendly display of a DigestAuthException
Since: http-client-tls-0.3.3
All information on how to connect to a host and what should be sent in the HTTP request.
If you simply wish to download from a URL, see parseRequest
.
The constructor for this data type is not exposed. Instead, you should use
either the defaultRequest
value, or parseRequest
to
construct from a URL, and then use the records below to make modifications.
This approach allows http-client to add configuration options without
breaking backwards compatibility.
For example, to construct a POST request, you could do something like:
initReq <- parseRequest "http://www.example.com/path" let req = initReq { method = "POST" }
For more information, please see http://www.yesodweb.com/book/settings-types.
Since 0.1.0
data RequestBody #
When using one of the RequestBodyStream
/ RequestBodyStreamChunked
constructors, you must ensure that the GivesPopper
can be called multiple
times. Usually this is not a problem.
The RequestBodyStreamChunked
will send a chunked request body. Note that
not all servers support this. Only use RequestBodyStreamChunked
if you
know the server you're sending to supports chunked request bodies.
Since 0.1.0
Instances
IsString RequestBody | Since 0.4.12 |
Defined in Network.HTTP.Client.Types fromString :: String -> RequestBody # | |
Monoid RequestBody | |
Defined in Network.HTTP.Client.Types mempty :: RequestBody # mappend :: RequestBody -> RequestBody -> RequestBody # mconcat :: [RequestBody] -> RequestBody # | |
Semigroup RequestBody | |
Defined in Network.HTTP.Client.Types (<>) :: RequestBody -> RequestBody -> RequestBody # sconcat :: NonEmpty RequestBody -> RequestBody # stimes :: Integral b => b -> RequestBody -> RequestBody # |
A simple representation of the HTTP response.
Since 0.1.0
Instances
Foldable Response | |
Defined in Network.HTTP.Client.Types fold :: Monoid m => Response m -> m # foldMap :: Monoid m => (a -> m) -> Response a -> m # foldMap' :: Monoid m => (a -> m) -> Response a -> m # foldr :: (a -> b -> b) -> b -> Response a -> b # foldr' :: (a -> b -> b) -> b -> Response a -> b # foldl :: (b -> a -> b) -> b -> Response a -> b # foldl' :: (b -> a -> b) -> b -> Response a -> b # foldr1 :: (a -> a -> a) -> Response a -> a # foldl1 :: (a -> a -> a) -> Response a -> a # elem :: Eq a => a -> Response a -> Bool # maximum :: Ord a => Response a -> a # minimum :: Ord a => Response a -> a # | |
Traversable Response | |
Functor Response | |
Show body => Show (Response body) | |
data HttpException #
An exception which may be generated by this library
Since: http-client-0.5.0
HttpExceptionRequest Request HttpExceptionContent | Most exceptions are specific to a Since: http-client-0.5.0 |
InvalidUrlException String String | A URL (first field) is invalid for a given reason (second argument). Since: http-client-0.5.0 |
Instances
Exception HttpException | |
Defined in Network.HTTP.Client.Types | |
Show HttpException | |
Defined in Network.HTTP.Client.Types showsPrec :: Int -> HttpException -> ShowS # show :: HttpException -> String # showList :: [HttpException] -> ShowS # |
data HttpExceptionContent #
StatusCodeException (Response ()) ByteString | Generated by the May include the beginning of the response body. Since: http-client-0.5.0 |
TooManyRedirects [Response ByteString] | The server responded with too many redirects for a request. Contains the list of encountered responses containing redirects in reverse chronological order; including last redirect, which triggered the exception and was not followed. Since: http-client-0.5.0 |
OverlongHeaders | Either too many headers, or too many total bytes in a single header, were returned by the server, and the memory exhaustion protection in this library has kicked in. Since: http-client-0.5.0 |
ResponseTimeout | The server took too long to return a response. This can
be altered via Since: http-client-0.5.0 |
ConnectionTimeout | Attempting to connect to the server timed out. Since: http-client-0.5.0 |
ConnectionFailure SomeException | An exception occurred when trying to connect to the server. Since: http-client-0.5.0 |
InvalidStatusLine ByteString | The status line returned by the server could not be parsed. Since: http-client-0.5.0 |
InvalidHeader ByteString | The given response header line could not be parsed Since: http-client-0.5.0 |
InvalidRequestHeader ByteString | The given request header is not compliant (e.g. has newlines) Since: http-client-0.5.14 |
InternalException SomeException | An exception was raised by an underlying library when performing the request. Most often, this is caused by a failing socket action or a TLS exception. Since: http-client-0.5.0 |
ProxyConnectException ByteString Int Status | A non-200 status code was returned when trying to connect to the proxy server on the given host and port. Since: http-client-0.5.0 |
NoResponseDataReceived | No response data was received from the server at all. This exception may deserve special handling within the library, since it may indicate that a pipelining has been used, and a connection thought to be open was in fact closed. Since: http-client-0.5.0 |
TlsNotSupported | Exception thrown when using a Since: http-client-0.5.0 |
WrongRequestBodyStreamSize Word64 Word64 | The request body provided did not match the expected size. Provides the expected and actual size. Since: http-client-0.4.31 |
ResponseBodyTooShort Word64 Word64 | The returned response body is too short. Provides the expected size and actual size. Since: http-client-0.5.0 |
InvalidChunkHeaders | A chunked response body had invalid headers. Since: http-client-0.5.0 |
IncompleteHeaders | An incomplete set of response headers were returned. Since: http-client-0.5.0 |
InvalidDestinationHost ByteString | The host we tried to connect to is invalid (e.g., an empty string). |
HttpZlibException ZlibException | An exception was thrown when inflating a response body. Since: http-client-0.5.0 |
InvalidProxyEnvironmentVariable Text Text | Values in the proxy environment variable were invalid. Provides the environment variable name and its value. Since: http-client-0.5.0 |
ConnectionClosed | Attempted to use a Since: http-client-0.5.0 |
InvalidProxySettings Text | Proxy settings are not valid (Windows specific currently) @since 0.5.7 |
Instances
Show HttpExceptionContent | |
Defined in Network.HTTP.Client.Types showsPrec :: Int -> HttpExceptionContent -> ShowS # show :: HttpExceptionContent -> String # showList :: [HttpExceptionContent] -> ShowS # |
notFound404 :: Status #
Not Found 404
hAccept :: HeaderName #
HTTP Header names according to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
hContentLength :: HeaderName #
HTTP Header names according to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
HTTP Header names according to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
methodPost :: Method #
HTTP Method constants.
formDataBody :: MonadIO m => [Part] -> Request -> m Request #
Add form data to the Request
.
This sets a new requestBody
, adds a content-type request header and changes the method to POST.
:: forall (m :: Type -> Type). Applicative m | |
=> Text | Name of the corresponding <input>. |
-> FilePath | File name to supply to the server. |
-> RequestBody | Data to upload. |
-> PartM m |
Construct a Part
from form name, filepath and a RequestBody
partFileRequestBody "who_calls" "caller.json" $ RequestBodyBS "{\"caller\":\"Jason J Jason\"}"
-- empty upload form partFileRequestBody "file" mempty mempty
The Part
does not have a content type associated with it.
:: forall (m :: Type -> Type). Applicative m | |
=> Text | Name of the corresponding <input>. |
-> ByteString | The body for this |
-> PartM m |
Make a Part
whose content is a strict ByteString
.
The Part
does not have a file name or content type associated
with it.
:: forall (m :: Type -> Type). Applicative m | |
=> Text | Name of the corresponding <input>. |
-> ByteString | The body for this |
-> PartM m |
Make a Part
whose content is a lazy ByteString
.
The Part
does not have a file name or content type associated
with it.
setGitHubHeaders :: Request -> Request Source #
Set the user-agent request header
:: HasTerm env | |
=> Request | |
-> Path Abs File | destination |
-> RIO env Bool | Was a downloaded performed (True) or did the file already exist (False)? |
Download the given URL to the given location. If the file already exists, no download is performed. Otherwise, creates the parent directory, downloads to a temporary file, and on file download completion moves to the appropriate destination.
Throws an exception if things go wrong
:: HasTerm env | |
=> DownloadRequest | |
-> Path Abs File | destination |
-> (Maybe Integer -> ConduitM ByteString Void (RIO env) ()) | custom hook to observe progress |
-> RIO env Bool | Whether a download was performed |
Copied and extended version of Network.HTTP.Download.download.
Has the following additional features: * Verifies that response content-length header (if present) matches expected length * Limits the download to (close to) the expected # of bytes * Verifies that the expected # bytes were downloaded (not too few) * Verifies md5 if response includes content-md5 header * Verifies the expected hashes
Throws VerifiedDownloadException. Throws IOExceptions related to file system operations. Throws HttpException.
verifiedDownloadWithProgress :: HasTerm env => DownloadRequest -> Path Abs File -> Text -> Maybe Int -> RIO env Bool Source #
data CheckHexDigest #
Instances
IsString CheckHexDigest | |
Defined in Network.HTTP.Download.Verified fromString :: String -> CheckHexDigest # | |
Show CheckHexDigest | |
Defined in Network.HTTP.Download.Verified showsPrec :: Int -> CheckHexDigest -> ShowS # show :: CheckHexDigest -> String # showList :: [CheckHexDigest] -> ShowS # |
data DownloadRequest #
A request together with some checks to perform.
Construct using the downloadRequest
smart constructor and associated
setters. The constructor itself is not exposed to avoid breaking changes
with additional fields.
Since: http-download-0.2.0.0
drRetryPolicyDefault :: RetryPolicy #
Default to retrying seven times with exponential backoff starting from one hundred milliseconds.
This means the tries will occur after these delays if necessary:
- 0.1s
- 0.2s
- 0.4s
- 0.8s
- 1.6s
- 3.2s
- 6.4s
data VerifiedDownloadException #
An exception regarding verification of a download.
WrongContentLength Request Int ByteString | |
WrongStreamLength Request Int Int | |
WrongDigest Request String CheckHexDigest String | |
DownloadHttpError HttpException |
Instances
(Show a, HashAlgorithm a) => HashCheck | |
mkDownloadRequest :: Request -> DownloadRequest #
Construct a new DownloadRequest
from the given Request
. Use associated
setters to modify the value further.
Since: http-download-0.2.0.0
setHashChecks :: [HashCheck] -> DownloadRequest -> DownloadRequest #
Set the hash checks to be run when verifying.
Since: http-download-0.2.0.0
setLengthCheck :: Maybe LengthCheck -> DownloadRequest -> DownloadRequest #
Set the length check to be run when verifying.
Since: http-download-0.2.0.0
setRetryPolicy :: RetryPolicy -> DownloadRequest -> DownloadRequest #
Set the retry policy to be used when downloading.
Since: http-download-0.2.0.0
setForceDownload :: Bool -> DownloadRequest -> DownloadRequest #
If True
, force download even if the file already exists. Useful for
download a resource which may change over time.