Network.GRPC.Client.Helpers

Set of helpers helping with writing gRPC clients with not much exposure of the http2-client complexity.

The GrpcClient handles automatic background connection-level window updates to prevent the connection from starving and pings to force a connection alive.

There is no automatic reconnection, retry, or healthchecking. These features are not planned in this library and should be added at higher-levels.

Documentation

data GrpcClient

A simplified gRPC Client connected via an HTTP2Client to a given server. Each call from one client will share similar headers, timeout, compression.

Constructors

GrpcClient

Fields

• _grpcClientHttp2Client :: Http2Client

  Underlying HTTP2 client.

• _grpcClientAuthority :: Authority

  Authority header of the server the client is connected to.

• _grpcClientHeaders :: [(ByteString, ByteString)]

  Extra HTTP2 headers to pass to every call (e.g., authentication tokens).

• _grpcClientTimeout :: Timeout

  Timeout for RPCs.

• _grpcClientCompression :: Compression

  Compression shared for every call and expected for every answer.

• _grpcClientBackground :: BackgroundTasks

  Running background tasks.

data BackgroundTasks

Constructors

BackgroundTasks

Fields

• backgroundWindowUpdate :: Async (Either ClientError ())

  Periodically give the server credit to use the connection.

• backgroundPing :: Async (Either ClientError ())

  Periodically ping the server.

data GrpcClientConfig

Configuration to setup a GrpcClient.

Constructors

GrpcClientConfig

Fields

• _grpcClientConfigHost :: !HostName

  Hostname of the server.

• _grpcClientConfigPort :: !PortNumber

  Port of the server.

• _grpcClientConfigHeaders :: ![(ByteString, ByteString)]

  Extra HTTP2 headers to pass to every call (e.g., authentication tokens).

• _grpcClientConfigTimeout :: !Timeout

  Timeout for RPCs.

• _grpcClientConfigCompression :: !Compression

  Compression shared for every call and expected for every answer.

• _grpcClientConfigTLS :: !(Maybe ClientParams)

  TLS parameters for the session.

• _grpcClientConfigGoAwayHandler :: GoAwayHandler

  HTTP2 handler for GoAways.

• _grpcClientConfigFallbackHandler :: FallBackFrameHandler

  HTTP2 handler for unhandled frames.

• _grpcClientConfigWindowUpdateDelay :: Int

  Delay in microsecond between to window updates.

• _grpcClientConfigPingDelay :: Int

  Delay in microsecond between to pings.

grpcClientConfigSimple :: HostName -> PortNumber -> UseTlsOrNot -> GrpcClientConfig

type UseTlsOrNot = Bool

tlsSettings :: UseTlsOrNot -> HostName -> PortNumber -> Maybe ClientParams

setupGrpcClient :: GrpcClientConfig -> ClientIO GrpcClient

close :: GrpcClient -> ClientIO ()

Cancels background tasks and closes the underlying HTTP2 client.

rawUnary

Arguments

:: (GRPCInput r i, GRPCOutput r o)

=> r

The RPC to call.

-> GrpcClient

An initialized client.

-> i

The input.

-> ClientIO (Either TooMuchConcurrency (RawReply o))

Run an unary query.

rawStreamServer

Arguments

:: (GRPCInput r i, GRPCOutput r o)

=> r

The RPC to call.

-> GrpcClient

An initialized client.

-> a

An initial state.

-> i

The input of the stream request.

-> (a -> HeaderList -> o -> ClientIO a)

A state-passing handler called for each server-sent output. Headers are repeated for convenience but are the same for every iteration.

-> ClientIO (Either TooMuchConcurrency (a, HeaderList, HeaderList))

Calls for a server stream of requests.

rawStreamClient

Arguments

:: (GRPCInput r i, GRPCOutput r o)

=> r

The RPC to call.

-> GrpcClient

An initialized client.

-> a

An initial state.

-> (a -> ClientIO (a, Either StreamDone (CompressMode, i)))

A state-passing step function to decide the next message.

-> ClientIO (Either TooMuchConcurrency (a, RawReply o))

Sends a streams of requests to the server.

Messages are submitted to the HTTP2 underlying client and hence this function can block until the HTTP2 client has some network credit.

rawSteppedBidirectional

Arguments

:: (GRPCInput r i, GRPCOutput r o)

=> r

The RPC to call.

-> GrpcClient

An initialized client.

-> a

An initial state.

-> RunBiDiStep i o a

The sequential program to iterate between sending and receiving messages.

-> ClientIO (Either TooMuchConcurrency a)

Starts a bidirectional ping-pong like stream with the server.

This handler is well-suited when the gRPC application has a deterministic protocols, that is, when after sending a message a client can know how many messages to wait for before sending the next message.

rawGeneralStream

Arguments

:: (GRPCInput r i, GRPCOutput r o)

=> r

The RPC to call.

-> GrpcClient

An initialized client.

-> a

An initial state for the incoming loop.

-> (a -> IncomingEvent o a -> ClientIO a)

A state-passing function for the incoming loop.

-> b

An initial state for the outgoing loop.

-> (b -> ClientIO (b, OutgoingEvent i b))

A state-passing function for the ougoing loop.

-> ClientIO (Either TooMuchConcurrency (a, b))

Starts a stream with the server.

This handler allows to concurrently write messages and wait for incoming messages.