Safe Haskell	None
Language	Haskell2010

Network.GRPC.Client.Helpers

Description

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.

Synopsis

data GrpcClient = GrpcClient {
- _grpcClientHttp2Client :: Http2Client
- _grpcClientAuthority :: Authority
- _grpcClientHeaders :: [(ByteString, ByteString)]
- _grpcClientTimeout :: Timeout
- _grpcClientCompression :: Compression
- _grpcClientBackground :: BackgroundTasks
}
data BackgroundTasks = BackgroundTasks {
- backgroundWindowUpdate :: Async ()
- backgroundPing :: Async ()
}
data GrpcClientConfig = GrpcClientConfig {
}
grpcClientConfigSimple :: HostName -> PortNumber -> UseTlsOrNot -> GrpcClientConfig
type UseTlsOrNot = Bool
tlsSettings :: UseTlsOrNot -> HostName -> PortNumber -> Maybe ClientParams
setupGrpcClient :: GrpcClientConfig -> IO GrpcClient
close :: GrpcClient -> IO ()
rawUnary :: (Service s, HasMethod s m) => RPC s m -> GrpcClient -> MethodInput s m -> IO (Either TooMuchConcurrency (RawReply (MethodOutput s m)))
unaryOutput :: (Applicative f, Field3 a1 b1 (Either c1 a2) (Either c1 b2)) => (a2 -> f b2) -> Either c2 (Either c3 a1) -> f (Either c2 (Either c3 b1))
rawStreamServer :: (Service s, HasMethod s m, MethodStreamingType s m ~ ServerStreaming) => RPC s m -> GrpcClient -> a -> MethodInput s m -> (a -> HeaderList -> MethodOutput s m -> IO a) -> IO (Either TooMuchConcurrency (a, HeaderList, HeaderList))
rawStreamClient :: (Service s, HasMethod s m, MethodStreamingType s m ~ ClientStreaming) => RPC s m -> GrpcClient -> a -> (a -> IO (a, Either StreamDone (CompressMode, MethodInput s m))) -> IO (Either TooMuchConcurrency (a, RawReply (MethodOutput s m)))
rawSteppedBidirectional :: (Service s, HasMethod s m, MethodStreamingType s m ~ BiDiStreaming) => RPC s m -> GrpcClient -> a -> RunBiDiStep s m a -> IO (Either TooMuchConcurrency a)
rawGeneralStream :: (Service s, HasMethod s m) => RPC s m -> GrpcClient -> a -> (a -> IncomingEvent s m a -> IO a) -> b -> (b -> IO (b, OutgoingEvent s m b)) -> IO (Either TooMuchConcurrency (a, b))

Documentation

data GrpcClient Source #

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 Source #

Constructors

BackgroundTasks
Fields backgroundWindowUpdate :: Async () Periodically give the server credit to use the connection. backgroundPing :: Async () Periodically ping the server.

data GrpcClientConfig Source #

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 Source #

type UseTlsOrNot = Bool Source #

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

setupGrpcClient :: GrpcClientConfig -> IO GrpcClient Source #

close :: GrpcClient -> IO () Source #

Cancels background tasks and closes the underlying HTTP2 client.

rawUnary Source #

Arguments

:: (Service s, HasMethod s m)
=> RPC s m	The RPC to call.
-> GrpcClient	An initialized client.
-> MethodInput s m	The input.
-> IO (Either TooMuchConcurrency (RawReply (MethodOutput s m)))

Run an unary query.

unaryOutput :: (Applicative f, Field3 a1 b1 (Either c1 a2) (Either c1 b2)) => (a2 -> f b2) -> Either c2 (Either c3 a1) -> f (Either c2 (Either c3 b1)) Source #

Prism helper to unpack an unary gRPC call output.

 out <- rawUnary rpc grpc method
   print $ out ^? unaryOutput . somefield

rawStreamServer Source #

Arguments

:: (Service s, HasMethod s m, MethodStreamingType s m ~ ServerStreaming)
=> RPC s m	The RPC to call.
-> GrpcClient	An initialized client.
-> a	An initial state.
-> MethodInput s m	The input of the stream request.
-> (a -> HeaderList -> MethodOutput s m -> IO a)	A state-passing handler called for each server-sent output. Headers are repeated for convenience but are the same for every iteration.
-> IO (Either TooMuchConcurrency (a, HeaderList, HeaderList))

Calls for a server stream of requests.

rawStreamClient Source #

Arguments

:: (Service s, HasMethod s m, MethodStreamingType s m ~ ClientStreaming)
=> RPC s m	The RPC to call.
-> GrpcClient	An initialized client.
-> a	An initial state.
-> (a -> IO (a, Either StreamDone (CompressMode, MethodInput s m)))	A state-passing step function to decide the next message.
-> IO (Either TooMuchConcurrency (a, RawReply (MethodOutput s m)))

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 Source #

Arguments

:: (Service s, HasMethod s m, MethodStreamingType s m ~ BiDiStreaming)
=> RPC s m	The RPC to call.
-> GrpcClient	An initialized client.
-> a	An initial state.
-> RunBiDiStep s m a	The sequential program to iterate between sending and receiving messages.
-> IO (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 Source #

Arguments

:: (Service s, HasMethod s m)
=> RPC s m	The RPC to call.
-> GrpcClient	An initialized client.
-> a	An initial state for the incoming loop.
-> (a -> IncomingEvent s m a -> IO a)	A state-passing function for the incoming loop.
-> b	An initial state for the outgoing loop.
-> (b -> IO (b, OutgoingEvent s m b))	A state-passing function for the ougoing loop.
-> IO (Either TooMuchConcurrency (a, b))

Starts a stream with the server.

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