Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Network.HTTP2.Client
Description
HTTP/2 client library.
Example:
{-# LANGUAGE OverloadedStrings #-} module Main where import Control.Concurrent.Async import qualified Control.Exception as E import qualified Data.ByteString.Char8 as C8 import Network.HTTP.Types import Network.Run.TCP (runTCPClient) -- network-run import Network.HTTP2.Client serverName :: String serverName = "127.0.0.1" main :: IO () main = runTCPClient serverName "80" $ runHTTP2Client serverName where cliconf host = ClientConfig "http" (C8.pack host) 20 runHTTP2Client host s = E.bracket (allocSimpleConfig s 4096) freeSimpleConfig (\conf -> run (cliconf host) conf client) client sendRequest = do let req0 = requestNoBody methodGet "/" [] client0 = sendRequest req0 $ \rsp -> do print rsp getResponseBodyChunk rsp >>= C8.putStrLn req1 = requestNoBody methodGet "/foo" [] client1 = sendRequest req1 $ \rsp -> do print rsp getResponseBodyChunk rsp >>= C8.putStrLn ex <- E.try $ concurrently_ client0 client1 case ex of Left e -> print (e :: HTTP2Error) Right () -> putStrLn "OK"
Synopsis
- run :: ClientConfig -> Config -> Client a -> IO a
- type Scheme = ByteString
- type Authority = ByteString
- data ClientConfig = ClientConfig {
- scheme :: Scheme
- authority :: Authority
- cacheLimit :: Int
- data Config = Config {
- confWriteBuffer :: Buffer
- confBufferSize :: BufferSize
- confSendAll :: ByteString -> IO ()
- confReadN :: Int -> IO ByteString
- confPositionReadMaker :: PositionReadMaker
- confTimeoutManager :: Manager
- confMySockAddr :: SockAddr
- confPeerSockAddr :: SockAddr
- allocSimpleConfig :: Socket -> BufferSize -> IO Config
- freeSimpleConfig :: Config -> IO ()
- type Client a = (forall b. Request -> (Response -> IO b) -> IO b) -> IO a
- data Request
- requestNoBody :: Method -> Path -> RequestHeaders -> Request
- requestFile :: Method -> Path -> RequestHeaders -> FileSpec -> Request
- requestStreaming :: Method -> Path -> RequestHeaders -> ((Builder -> IO ()) -> IO () -> IO ()) -> Request
- requestStreamingUnmask :: Method -> Path -> RequestHeaders -> ((forall x. IO x -> IO x) -> (Builder -> IO ()) -> IO () -> IO ()) -> Request
- requestBuilder :: Method -> Path -> RequestHeaders -> Builder -> Request
- type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker
- data NextTrailersMaker
- defaultTrailersMaker :: TrailersMaker
- setRequestTrailersMaker :: Request -> TrailersMaker -> Request
- data Response
- responseStatus :: Response -> Maybe Status
- responseHeaders :: Response -> HeaderTable
- responseBodySize :: Response -> Maybe Int
- getResponseBodyChunk :: Response -> IO ByteString
- getResponseTrailers :: Response -> IO (Maybe HeaderTable)
- type Method = ByteString
- type Path = ByteString
- data FileSpec = FileSpec FilePath FileOffset ByteCount
- type FileOffset = Int64
- type ByteCount = Int64
- data HTTP2Error
- = ConnectionIsClosed
- | ConnectionErrorIsReceived ErrorCode StreamId ReasonPhrase
- | ConnectionErrorIsSent ErrorCode StreamId ReasonPhrase
- | StreamErrorIsReceived ErrorCode StreamId
- | StreamErrorIsSent ErrorCode StreamId ReasonPhrase
- | BadThingHappen SomeException
- | GoAwayIsSent
- newtype ErrorCode where
- ErrorCode Word32
- pattern NoError :: ErrorCode
- pattern ProtocolError :: ErrorCode
- pattern InternalError :: ErrorCode
- pattern FlowControlError :: ErrorCode
- pattern SettingsTimeout :: ErrorCode
- pattern StreamClosed :: ErrorCode
- pattern FrameSizeError :: ErrorCode
- pattern RefusedStream :: ErrorCode
- pattern Cancel :: ErrorCode
- pattern CompressionError :: ErrorCode
- pattern ConnectError :: ErrorCode
- pattern EnhanceYourCalm :: ErrorCode
- pattern InadequateSecurity :: ErrorCode
- pattern HTTP11Required :: ErrorCode
- defaultReadN :: Socket -> IORef (Maybe ByteString) -> Int -> IO ByteString
- type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel)
- type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount
- data Sentinel
- defaultPositionReadMaker :: PositionReadMaker
Runner
run :: ClientConfig -> Config -> Client a -> IO a #
Running HTTP/2 client.
type Scheme = ByteString #
"http" or "https".
type Authority = ByteString #
Authority.
Runner arguments
data ClientConfig #
Client configuration
Constructors
ClientConfig | |
Fields
|
HTTP/2 configuration.
Constructors
Config | |
Fields
|
allocSimpleConfig :: Socket -> BufferSize -> IO Config #
Making simple configuration whose IO is not efficient. A write buffer is allocated internally.
freeSimpleConfig :: Config -> IO () #
Deallocating the resource of the simple configuration.
HTTP/2 client
Request
Request from client.
Creating request
requestNoBody :: Method -> Path -> RequestHeaders -> Request #
Creating request without body.
requestFile :: Method -> Path -> RequestHeaders -> FileSpec -> Request #
Creating request with file.
requestStreaming :: Method -> Path -> RequestHeaders -> ((Builder -> IO ()) -> IO () -> IO ()) -> Request #
Creating request with streaming.
requestStreamingUnmask :: Method -> Path -> RequestHeaders -> ((forall x. IO x -> IO x) -> (Builder -> IO ()) -> IO () -> IO ()) -> Request #
Like requestStreaming
, but run the action with exceptions masked
requestBuilder :: Method -> Path -> RequestHeaders -> Builder -> Request #
Creating request with builder.
Trailers maker
type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker #
Trailers maker. A chunks of the response body is passed
with Just
. The maker should update internal state
with the ByteString
and return the next trailers maker.
When response body reaches its end,
Nothing
is passed and the maker should generate
trailers. An example:
{-# LANGUAGE BangPatterns #-} import Data.ByteString (ByteString) import qualified Data.ByteString.Char8 as C8 import Crypto.Hash (Context, SHA1) -- cryptonite import qualified Crypto.Hash as CH -- Strictness is important for Context. trailersMaker :: Context SHA1 -> Maybe ByteString -> IO NextTrailersMaker trailersMaker ctx Nothing = return $ Trailers [("X-SHA1", sha1)] where !sha1 = C8.pack $ show $ CH.hashFinalize ctx trailersMaker ctx (Just bs) = return $ NextTrailersMaker $ trailersMaker ctx' where !ctx' = CH.hashUpdate ctx bs
Usage example:
let h2rsp = responseFile ... maker = trailersMaker (CH.hashInit :: Context SHA1) h2rsp' = setResponseTrailersMaker h2rsp maker
data NextTrailersMaker #
Either the next trailers maker or final trailers.
Constructors
NextTrailersMaker TrailersMaker | |
Trailers [Header] |
defaultTrailersMaker :: TrailersMaker #
TrailersMake to create no trailers.
setRequestTrailersMaker :: Request -> TrailersMaker -> Request #
Setting TrailersMaker
to Response
.
Response
Response from server.
Accessing response
responseStatus :: Response -> Maybe Status #
Getting the status of a response.
responseHeaders :: Response -> HeaderTable #
Getting the headers from a response.
responseBodySize :: Response -> Maybe Int #
Getting the body size from a response.
getResponseBodyChunk :: Response -> IO ByteString #
Reading a chunk of the response body.
An empty ByteString
returned when finished.
getResponseTrailers :: Response -> IO (Maybe HeaderTable) #
Reading response trailers.
This function must be called after getResponseBodyChunk
returns an empty.
Types
type Method = ByteString #
HTTP method (flat string type).
type Path = ByteString #
Path.
File specification.
Constructors
FileSpec FilePath FileOffset ByteCount |
type FileOffset = Int64 #
Offset for file.
Error
data HTTP2Error #
The connection error or the stream error.
Stream errors are treated as connection errors since
there are no good recovery ways.
ErrorCode
in connection errors should be the highest stream identifier
but in this implementation it identifies the stream that
caused this error.
Constructors
ConnectionIsClosed | |
ConnectionErrorIsReceived ErrorCode StreamId ReasonPhrase | |
ConnectionErrorIsSent ErrorCode StreamId ReasonPhrase | |
StreamErrorIsReceived ErrorCode StreamId | |
StreamErrorIsSent ErrorCode StreamId ReasonPhrase | |
BadThingHappen SomeException | |
GoAwayIsSent |
Instances
Exception HTTP2Error # | |
Defined in Network.HTTP2.Arch.Types Methods toException :: HTTP2Error -> SomeException # fromException :: SomeException -> Maybe HTTP2Error # displayException :: HTTP2Error -> String # | |
Show HTTP2Error # | |
Defined in Network.HTTP2.Arch.Types Methods showsPrec :: Int -> HTTP2Error -> ShowS show :: HTTP2Error -> String showList :: [HTTP2Error] -> ShowS |
The type for raw error code.
Bundled Patterns
pattern NoError :: ErrorCode | The type for error code. See https://www.rfc-editor.org/rfc/rfc9113#ErrorCodes. |
pattern ProtocolError :: ErrorCode | |
pattern InternalError :: ErrorCode | |
pattern FlowControlError :: ErrorCode | |
pattern SettingsTimeout :: ErrorCode | |
pattern StreamClosed :: ErrorCode | |
pattern FrameSizeError :: ErrorCode | |
pattern RefusedStream :: ErrorCode | |
pattern Cancel :: ErrorCode | |
pattern CompressionError :: ErrorCode | |
pattern ConnectError :: ErrorCode | |
pattern EnhanceYourCalm :: ErrorCode | |
pattern InadequateSecurity :: ErrorCode | |
pattern HTTP11Required :: ErrorCode |
Instances
Read ErrorCode # | |
Defined in Network.HTTP2.Frame.Types | |
Show ErrorCode # | |
Eq ErrorCode # | |
Ord ErrorCode # | |
Defined in Network.HTTP2.Frame.Types |
RecvN
defaultReadN :: Socket -> IORef (Maybe ByteString) -> Int -> IO ByteString #
Naive implementation for readN.
Position read for files
type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel) #
Making a position read and its closer.
type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount #
Position read for files.
Manipulating a file resource.
defaultPositionReadMaker :: PositionReadMaker #
Position read based on Handle
.