Proposal to add runtime APIs: Deno.connectGrpc and Deno.listenGrpc

[disjukr]

We don't have a proper way to use gRPC protocol with Deno right now.

gRPC uses HTTP2 trailer for sending grpc-status, which is important for implementing gRPC. However, since Deno tries to provide Web-compatible interfaces, APIs like fetch and Deno.serveHttp do not provide any ways to read or write HTTP2 trailers.

It is also undesirable to use FFI for gRPC. Native gRPC libraries like Tonic will have to be run in executors like Tokio, but Deno's own Tokio event loop is not exposed. So they can't be run in tandem with Deno, as otherwise they will block Deno.

It is possible to use Deno.connectTls and Deno.listenTls to build entire HTTP2 and gRPC stack with JS. But it is hard to leverage HTTP2 implementation of Deno and would result in a performance decrease.

So I propose to add new runtime APIs for Deno.connectGrpc and Deno.listenGrpc, as follows.

declare namespace Deno {
  export function connectGrpc(
    options: ConnectGrpcOptions,
  ): Promise<GrpcChannel>;
  export interface ConnectGrpcOptions {
    // https://grpc.github.io/grpc/core/md_doc_naming.html
    host: string | URL;
    privateKey?: string;
    certChain?: string;
    caCerts?: string[];
  }
  export interface GrpcChannel extends Closer {
    call(request: GrpcRequest): GrpcResponse;
  }

  export function listenGrpc(options: ListenGrpcOptions): GrpcListener;
  export interface ListenGrpcOptions {
    addr: string;
    privateKey?: string;
    certChain?: string;
  }
  export interface GrpcListener
    extends AsyncIterableIterator<GrpcRequestEvent>, Closer {}
  export interface GrpcRequestEvent {
    readonly request: GrpcRequest;
    sendHeader(header: GrpcMetadata): Promise<void>;
    sendMessage(message: Uint8Array): Promise<void>;
    sendTrailer(trailer: GrpcMetadata): Promise<void>;
  }

  export interface GrpcRequest {
    metadata: GrpcMetadata;
    messages: AsyncGenerator<Uint8Array>;
  }
  export interface GrpcResponse {
    header: Promise<GrpcMetadata>;
    messages: AsyncGenerator<Uint8Array>;
    trailer: Promise<GrpcMetadata>;
  }
  export interface GrpcMetadata {
    [key: string]: string | Uint8Array;
  }
}

This is arguably a lower level API (or too high to someone. I wanted to make the interface simple). But we necessarily need this general design because gRPC supports not only Protobuf but also other serialization formats like FlatBuffers.
I would expect that higher-level API is to be provided by codegen layers like Pbkit as Protobuf already requires codegen anyway.

[ghost]

What is the point of offering an API to implement gRPC clients and servers, rather than directly supporting gRPC clients and servers via the Deno CLI?
One interest I can see is to simplify the support of protocols like Connect or gRPC-Web via a package, but I don't know if it is enough to justify the complexity? (Especially since it would be ideal to support them directly in Deno.)

[ghost]

Thanks a lot for your answers, it's clearer for me!
I really liked the idea of having the code generation directly integrated into Deno, maybe even completely transparently, but that's probably not very useful in practice.

[reyawn]

If we could just find a way to just expose the missing bits of the HTTP2 spec to support more advanced uses like a GRPC implementation that would be perfect. This would probably be more useful in general than implementing and supporting GRPC itself as part of the runtime API.

This could mean exposing a lower-level HTTP API that could, for example, be used to implement the existing fetch-based HTTP server. The existing fetch stuff already has some "inner" entities as part of its implementation, perhaps some of this could be exposed in a more elegant way with this sort of missing functionality.

[ghost]

@reyawn From what I understand, the fetch API, following old discussions, does not allow to retrieve trailers. But if I'm not mistaken, this is the only thing missing.

So maybe the best solution is to see at WinterCG level if there is no way to make these trailers available. That would solve the problem in an elegant way.

I'm not sure I understand everything yet though.

[danopia]

Hi, I just took a brief excursion thru hitting firestore.googleapis.com gRPCs from Deno :) (I've ported another nodejs http2 impl up to w3c streams etc. to try doing a more serious take on user-code gRPC)

@reyawn From what I understand, the fetch API, following old discussions, does not allow to retrieve trailers. But if I'm not mistaken, this is the only thing missing.

Trailers definitely look like the big missing piece in fetch(), and yea, no apparent plans to spec it. You cannot receive gRPC errors at all without trailers! if you try sending a gRPC thru fetch today you will likely get back an empty 200 OK and literally nothing else. (Similarly, serving gRPC requires the ability to send trailers)

But also grpc wants to receive the HTTP2 RST_STREAM code (stream reset reason, when the server must abandon a request) in order to translate it into grpc error codes like INTERNAL or UNAVAILABLE. The spec has a table. Not critical to have, but sounds important IMO to offer spec-complete gRPC.

So, trailers and RST_STREAM visibility seem like the needed bits to satisfy the spec. But just to unnerve a little, grpc-web proxy spec says that grpc HTTP/2 wants to be aware of HTTP/2 framing, and that browser APIs will never expose that framing:

For the gRPC-Web protocol, we have decided on the following design goals:
[...] decouple from HTTP/2 framing which is not, and will never be, directly exposed by browsers [...]

[ghost]

Thank you very much for these details! I didn't know about RST_STREAM. 🙏

[mmastrac]

I'm currently working on modernizing our HTTP implementation to live on top of Hyper 1.0 and refactoring this code pretty significantly. gRPC will be next on my list, so I'll make sure that we're in a good place to support trailers/etc, at least on the Deno.serve side.

[reyawn]

@mmastrac That's fantastic. Ultimately it would be ideal for new libraries with great backing and momentum like https://github.com/bufbuild/connect-es to be able to utilize this functionality in a similar mechanism to other integrations (fastify, nodejs vanilla http2 server, etc)! connect-es has minimal dependencies (e.g. nothing like the old, non-spec-compliant, and troublesome-to-use grpc-js, protobufjs, etc libraries in the ecosystem), fully implements GRPC, and best of all is fully ESM-compliant so should be a great fit for Deno.