http2-client-grpc: Implement gRPC-over-HTTP2 clients.

[ bsd3, library, network ] [ Propose Tags ]

A gRPC over http2-client using proto-lens to generate client code.


[Skip to Readme]

Downloads

Versions [RSS] 0.1.0.0, 0.2.0.0, 0.2.0.1, 0.3.0.0, 0.4.0.0, 0.5.0.0, 0.5.0.1, 0.5.0.2, 0.5.0.3, 0.5.0.4, 0.6.0.0, 0.7.0.0, 0.8.0.0
Change log Changelog.md
Dependencies async (>=2.2 && <2.3), base (>=4.11 && <5), binary (>=0.8 && <0.9), bytestring (>=0.10.8 && <0.10.9), case-insensitive (>=1.2.0 && <1.3), data-default-class (>=0.1 && <0.2), http2 (>=1.6 && <1.7), http2-client (>=0.8 && <0.9), http2-grpc-types (>=0.3 && <0.4), lens (>=4.16 && <4.17), proto-lens (>=0.4 && <0.5), text (>=1.2 && <1.3), tls (>=1.4 && <1.5) [details]
License BSD-3-Clause
Copyright 2017 Lucas DiCioccio
Author Lucas DiCioccio
Maintainer lucas@dicioccio.fr
Category Network
Home page https://github.com/lucasdicioccio/http2-client-grpc#readme
Source repo head: git clone https://github.com/lucasdicioccio/http2-client-grpc
Uploaded by LucasDiCioccio at 2018-09-15T10:39:45Z
Distributions
Reverse Dependencies 9 direct, 1 indirect [details]
Downloads 6330 total (38 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2018-09-15 [all 1 reports]

Readme for http2-client-grpc-0.5.0.4

[back to package description]

http2-client-grpc

A native HTTP2 gRPC client library using proto-lens and http2-client.

Summary

This project provides a library that leverages the code generated using proto-lens (in particular, proto-lens-protoc) to implement the client-side of gRPC services.

Usage

Prerequisites

In addition to a working Haskell dev environment, you need to:

  • build the proto-lens-protoc executable (proto-lens)
  • install the protoc executable

Adding .proto files to a Haskell package

In order to run gRPC:

  • generate the Proto stubs in some gen directory

A single protoc invocation may be enough for both Proto and GRPC outputs:

protoc  "--plugin=protoc-gen-haskell-protolens=${protolens}" \
    --haskell-protolens_out=./gen \
    -I "${protodir1} \
    -I "${protodir2} \
    ${first.proto} \
    ${second.proto}
  • add the gen sourcedir for the generated to your .cabal/package.yaml file (cf. 'hs-source-dirs').
  • add the generated Proto modules to the 'exposed-modules' (or 'other-modules') keys

A reliable way to list the module names is the following bash invocation:

find gen -name "*.hs" | sed -e 's/gen\///' | sed -e 's/\.hs$//' | tr '/' '.'

Unlike proto-lens, this project does not yet provide a modified Setup.hs. As a result, we cannot automate these steps from within Cabal/Stack. Hence, you'll have to automate these steps outside your Haskell toolchain.

Calling a GRPC service

In short, use http2-client with the Network.GRPC.call function and let the types guide you.

Example

You'll find an example leveraging the awesome grpcb.in service at https://github.com/lucasdicioccio/http2-client-grpc-example .

gRPC service mapping

The Protobuf format specifies the notion of Service which can have one or more RPCs. The gRPC protocal maps these services onto HTTP2 headers and HTTP2 frames. In general, gRPC implementation generate one inlined function per RPC. This implementation differs by decoupling the HTTP2 transport and leveraging generics to provide generic functions. This design allows the Network.GRPC.call to be type safe and multi-usage. For instance, you can wrap this function with whatever metrics/benchmark code and have all your RPC calls be monitored in a uniform way.

Status

This library is currently an early-stage library. Expect breaking changes.

Next steps

  • provide function to map raw results into commonly-understood GRPC errors
  • (nice-to-have) support effectful compression (Zlib pure compression is supported)