warp-grpc: A minimal gRPC server on top of Warp.

[ bsd3, library, networking ] [ Propose Tags ]

Please see the README on Github at https://github.com/lucasdicioccio/warp-grpc#readme


[Skip to Readme]
Versions [faq] 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.0.3
Change log ChangeLog.md
Dependencies async (>=2.2.1 && <3), base (>=4.11 && <5), binary (>=0.8.5 && <0.9), bytestring (>=0.10.8 && <0.11), case-insensitive (>=1.2.0 && <1.3), http-types (==0.12.*), http2-grpc-types (==0.3.*), proto-lens (>=0.3 && <0.5), wai (==3.2.*), warp (>=3.2.24 && <3.3), warp-tls (==3.2.*) [details]
License BSD-3-Clause
Copyright 2017 Lucas DiCioccio
Author Lucas DiCioccio
Maintainer lucas@dicioccio.fr
Revised Revision 1 made by LucasDiCioccio at Sat Sep 15 09:59:55 UTC 2018
Category Networking
Home page https://github.com/lucasdicioccio/warp-grpc#readme
Bug tracker https://github.com/lucasdicioccio/warp-grpc/issues
Source repo head: git clone https://github.com/lucasdicioccio/warp-grpc
Uploaded by LucasDiCioccio at Mon Sep 10 20:31:29 UTC 2018
Distributions NixOS:0.1.0.3
Downloads 338 total (49 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2018-09-10 [all 1 reports]

Modules

[Index] [Quick Jump]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

For package maintainers and hackage trustees


Readme for warp-grpc-0.1.0.3

[back to package description]

warp-grpc

A gRPC server implementation on top of Warp's HTTP2 handler. The lib also contains a demo sever using the awesome grpcb.in Proto. The current release is an advanced technical demo, expect a few breaking changes.

Design

The library implements gRPC using a WAI middleware for a set of gRPC endpoints. Endpoint handlers differ depending of the streaming/unary-ty of individual RPCs. Bidirectional streams will be supported next.

There is little specification around the expected allowed observable states in gRPC, hence the types this library presents make conservative choices: unary RPCs expect an input before providing an output. Client stream allows to return an output only when the client has stopped streaming. Server streams wait for an input before starting to iterate sending outputs.

Usage

Generate some proto-lens code from .proto files, ideally in a separate library. Import this library and the generated proto-lens code to implement handlers for the service stanzas defined in the .proto files (see Haddocks). Finally, serve warp over TLS`.

Example

Please refer to https://github.com/lucasdicioccio/warp-grpc-example for an example.

Next steps

  • Helper to set metadatas (a.k.a., headers and trailers).
    • (API-breaking) some or all handlers will get an IO-step to return extra metadata
  • Helper to map request headerlists into client metadatas (probably in http2-grpc-types)

Limitations

  • Only supports "h2" with TLS (I'd argue it's a feature, not a bug. Don't @-me)
  • Some valid gRPC applications may not be expressible directly on top of warp because sending HTTP2 trailers (i.e., signalling the server's desire to stop sending messages) is correlated with closing the HTTP2 stream (i.e., stop accepting client messages). Hence it's not feasible to create a bidirectional stream that terminates on the server end while continuing to ingest client messages. This use case, however, seems like a corner case.