Spike: gRPC support for controllers

[bajtos]

What's needed to make the current REST interface a plugable component and make it easy to add gRPC support as another component.

See #440

[bajtos]

What have I learned so far:

• grpc has an official node.js server & client available via https://www.npmjs.com/package/grpc
• each gRPC operation has two inputs: a request message (either a single object or a stream of objects of the same type) and metadata (a mapping from string keys to arbitrary values eventually encoded as strings in HTTP2)
• each gRPC operation has two outputs: a response message (either a single object or a stream of objects of the same type) and metadata (a mapping from string keys to arbitrary values eventually encoded as strings in HTTP2
• multiple input arguments are intentionally not supported and won't be implemented - see RPC service multiple parameter support, For existing services which uses proxy instead of stub protocolbuffers/protobuf#976 (comment)
• authentication is handled via metadata, see https://grpc.io/docs/guides/auth.html and https://grpc.io/docs/guides/wire.html#example
• grpc layer abstracts away all transport details (like HTTP2 request/response objects), remote methods have access only to the input message object/stream and metadata object/map.

[bajtos]

Messages definitions (schemas) are based on Protocol Buffers - see https://developers.google.com/protocol-buffers/docs/overview. (Compare to Swagger/OpenAPI Spec which is based on JSON Schema.)

[bajtos]

@raymondfeng @kjdelisle I have the first iteration of my gRPC spike ready for a high-level review, see #571. Please focus more on the developer experience of people using loopback next, the actual implementation is intentionally dirty.

My next step is to bring in Sequence concept to allow applications to customize the gRPC request handling flow and then try to extend our authentication component to support gRPC too.

---

I have a major concern about the official grpc implementation for Node.js (https://www.npmjs.com/package/grpc): it is a thin wrapper around C/C++ based implementation, which has several downsides:

• We are introducing a native addon. Users will need a correctly configured build environment on their dev/test/production machines, this used to be a major pain point in the past.

• The grpc server implementation is inside the C/C++ code, it creates a parallel networking (TCP & HTTP2) stack to the one included in Node.js. My main concern is that we are loosing visibility and inspectability. The usual tools for monitoring Node.js app performance (CPU usage analysis, event-loop latency) will not work for the gRPC part. Similarly for error handling and post-mortem debugging.

BTW, both the server and the client are callback-based only and do not support Promise-style invocation. We will need wrappers to support our async/await style, as can be already seen in my spike pull request. Not a big deal deal, but it adds a bit of extra complexity.

---

I started my spike with the easiest path, which is to describe the RPC API in a proto file. I think this is similar to API-first approach for building REST APIs, where we start with OpenAPI Spec document.

const helloService = grpc.load(path.join(__dirname, 'hello.proto')).hello;

@service(helloService.Greeter.service)
class MyController implements Greeter {
  hello({name}: HelloRequest): HelloResponse {
    return {message: `hello ${name}`};
  }
}

Do we want to support code-first approach too, where the service/payload specs are built dynamically from the metadata provided by decorators? I am not very familiar with protocol buffers and the implementation used by gRPC in particular, so it's hard to tell for me how easy/difficult this will be to implement.

The .proto format provides quite a lot of type information about the services, request and response payloads. I think it will be very valuable to generate TypeScript interfaces representing the entities defined in .proto files. On the second thought, I think something similar can be done for people starting with an OpenAPI Spec document too. Obviously, this is out of scope of this initial spike and possibly even Core-GA release, but I'd like to know your thoughts - is this something to explore (i.e. create follow-up GitHub issues)?

On a related note: gRPC supports static and dynamic loading of proto specs. My initial spike is using dynamic loading, I think we should check static loading too to understand the differences. It may affect the way how we want to work with .proto and .d.ts files.

[ritch]

I would be -1 for generating a HelloRequest type def from proto, since the whole point is that the proto has the type def already.

Does TypeScript allow you to define types dynamically (eg. plug into the type loading system and add some types)? Seems like a pretty great thing to have for our use cases... eg. OpenAPI schemas => types, protos => types, etc.

Having redundant definitions of types seems like a bad idea (hello.proto + HelloRequest.ts), but it would be better than no types at all. All of the above applies to OpenAPI definitions/schemas.