Merge pull request #217 from well-typed/edsko/readme-interop

Add interop matrix to README

README.md

@@ -1,23 +1,95 @@
-# Haskell library providing [`gRPC`](https://grpc.io/) client and server
+# `grapesy`: industrial strength [gRPC][grpc:website] library for Haskell
 
-The `grapesy` Haskell library provides a `gRPC` server and client.
+Haskell library providing [`gRPC`][grpc:website] client and server.
 
-This is work in progress; it is **NOT YET READY FOR USE**.
+## Interoperability matrix
 
-It currently depends on an unreleased version of `http2`; see
-[`cabal.project`](cabal.project).
+The `gRPC` framework comes with a test suite that [tests interoperability
+between implementations][grpc:interop] as well compliance to the `gRPC`
+specification. As the table below shows, `grapesy` passes all of these tests,
+apart from the Open Request Cost Aggregation (ORCA) tests, which is [not yet
+supported][grapesy:issue:72-orca] by grapesy.
 
-## Documentation
+### Legend and version information
 
-* [Description of the demo](demo.md)
-* [Project status](status.md)
+Legend:
 
-## Comparison to related packages
+* ✅ passed
+* ❌ failed
+* ❔ not supported by the reference (or reference does not conform to the gRPC
+  specification)
+* 🚫 not supported by `grapesy`
 
-* Unlike
-  [`http2-client-grpc`](https://hackage.haskell.org/package/http2-client-grpc),
-  `grapesy` uses the HTTP2 client from
-  [`http2`](https://hackage.haskell.org/package/http2) rather than from
-  [`http2-client`](https://hackage.haskell.org/package/http2-client).
-* Unlike [`grpc-haskell`](https://hackage.haskell.org/package/grpc-haskell), it
-  does not make use of any C or C++ libraries (native Haskell only).
+We last tested against version
+[v1.62.0](https://github.com/grpc/grpc/releases/tag/v1.62.0) (released Feb 20,
+2024).
+
+### `grapesy` server versus reference client
+
+| Test                          | Python | C++  | Go | Java | grapesy |
+| ----------------------------- | ------ | ---- | -- | ---- | ------- |
+| `cancel_after_begin`          | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `cancel_after_first_response` | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `client_compressed_streaming` | ❔      | ✅    | ❔  | ✅    | ✅       |
+| `client_compressed_unary`     | ❔      | ✅    | ❔  | ✅    | ✅       |
+| `client_streaming`            | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `custom_metadata`             | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `empty_stream`                | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `empty_unary`                 | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `large_unary`                 | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `orca_oob`                    | 🚫      | 🚫    | 🚫  | 🚫    | 🚫       |
+| `orca_per_rpc`                | 🚫      | 🚫    | 🚫  | 🚫    | 🚫       |
+| `ping_pong`                   | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `server_compressed_streaming` | ❔      | ✅    | ❔  | ✅    | ✅       |
+| `server_compressed_unary`     | ❔      | ✅    | ❔  | ✅    | ✅       |
+| `server_streaming`            | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `special_status_message`      | ✅      | ❔    | ✅  | ✅    | ✅       |
+| `status_code_and_message`     | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `timeout_on_sleeping_server`  | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `unimplemented_method`        | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `unimplemented_service`       | ✅      | ✅    | ✅  | ✅    | ✅       |
+
+### `grapesy` client versus reference server
+
+| Test                          | Python | C++  | Go | Java | grapesy |
+| ----------------------------- | ------ | ---- | -- | ---- | ------- |
+| `cancel_after_begin`          | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `cancel_after_first_response` | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `client_compressed_streaming` | ❔      | ✅    | ❔  | ❔    | ✅       |
+| `client_compressed_unary`     | ❔      | ✅    | ❔  | ❔    | ✅       |
+| `client_streaming`            | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `custom_metadata`             | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `empty_stream`                | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `empty_unary`                 | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `large_unary`                 | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `orca_oob`                    | 🚫      | 🚫    | 🚫  | 🚫    | 🚫       |
+| `orca_per_rpc`                | 🚫      | 🚫    | 🚫  | 🚫    | 🚫       |
+| `ping_pong`                   | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `server_compressed_streaming` | ❔      | ✅    | ❔  | ❔    | ✅       |
+| `server_compressed_unary`     | ❔      | ✅    | ❔  | ✅    | ✅       |
+| `server_streaming`            | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `special_status_message`      | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `status_code_and_message`     | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `timeout_on_sleeping_server`  | ✅      | ✅    | ✅  | ❔    | ✅       |
+| `unimplemented_method`        | ✅      | ✅    | ✅  | ✅    | ✅       |
+| `unimplemented_service`       | ✅      | ✅    | ✅  | ✅    | ✅       |
+
+### Unsupported tests
+
+There are additional tests that are not supported by `grapesy`, but since these
+are not supported by _any_ of the reference implementations that we tested, we
+did not consider them any further. The full list is:
+
+* [`cacheable_unary`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#cacheable_unary)
+* [`compute_engine_creds`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#compute_engine_creds)
+* [`jwt_token_creds`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#jwt_token_creds)
+* [`oauth2_auth_token`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#oauth2_auth_token)
+* [`per_rpc_creds`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#per_rpc_creds)
+* [`google_default_credentials`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#google_default_credentials)
+* [`compute_engine_channel_credentials`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptionsmd#compute_engine_channel_credentials),
+* [`rpc_soak`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#rpc_soak)
+* [`channel_soak`](https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md#channel_soak)
+
+[grpc:website]: https://grpc.io/
+[grpc:interop]: https://github.com/grpc/grpc/tree/master/tools/interop_matrix
+[grapesy:issue:72-orca]: https://github.com/well-typed/grapesy/issues/72

src/Network/GRPC/Spec/RPC.hs

@@ -32,7 +32,7 @@ type family Output (rpc :: k) :: Type
 -- Note on encoding: the gRPC specification does not say anything about text
 -- encoding issues for paths (service names and method names) or message types.
 -- The Protobuf compiler (by far the most common instantation of gRPC) does not
--- allow for non-ASCII character at all ("nterpreting non ascii codepoint").
+-- allow for non-ASCII character at all ("interpreting non ascii codepoint").
 -- We therefore punt on the encoding issue here, and use bytestrings. /If/
 -- applications want to use non-ASCII characters, they can choose their own
 -- encoding.