docs: add documentation for streams and TLS

Signed-off-by: NorthBlue333 <[email protected]>

Author: NorthBlue333

README.md

@@ -6,6 +6,11 @@
 
 The `@loopback/grpc` component enables LoopBack 4 as a [gRPC](https://grpc.io/) Server. Also it provides with a gRPC decorator to define your RPC Method implementations from your Application Controllers.
 
+### Features
+
+- Handles unary, client streaming, server streaming and bidirectional streaming calls
+- Provides options for TLS and mTLS
+
 ## Installation
 
 Install the `@loopback/grpc` component in your LoopBack 4 Application.
@@ -18,10 +23,10 @@ $ npm install --save @loopback/grpc
 
 ```js
 import {Application} from '@loopback/core';
-import {GrpcComponent, Config} from '@loopback/grpc';
-import {GreeterCtrl} from './controllers/greeter/greeter.ctrl';
+import {GrpcComponent, GrpcComponentConfig} from '@loopback/grpc';
+import {GreeterController} from './controllers/greeter.controller';
 // Grpc Configurations are optional.
-const config: Config.Component = {
+const config: GrpcComponentConfig = {
   /* Optional Configs */
 };
 // Pass the optional configurations
@@ -30,13 +35,15 @@ const app = new Application({
 });
 // Add Grpc as Component
 app.component(GrpcComponent);
-// Bind GreeterCtrl to the LoopBack Application
-app.controller(GreeterCtrl);
+// Bind GreeterController to the LoopBack Application
+// only if your Boot Mixins do not load this directory
+// see https://loopback.io/doc/en/lb4/Booting-an-Application.html
+// app.controller(GreeterController);
 // Start App
 app.start();
 ```
 
-## Grpc auto-generated code
+## gRPC auto-generated code
 
 The `@loopback/grpc` extension provides you with auto-generated interfaces and configurations for strict development.
 
@@ -46,71 +53,196 @@ Example:
 
 ```sh
 - app
+| - protos
+| | - greeter.proto
+| - protos-ts
 | - controllers
-| | - greeter
-| | | - greeter.proto
-| | | - greeter.ctrl.ts
+| | - greeter.controller.ts
 ```
 
 Once you start your app for first time it will automatically create your typescript interfaces from the `greeter.proto` file.
 
 ```sh
 - app
+| - protos
+| | - greeter.proto
+| - protos-ts
+| | - greeter.ts <--- Auto-generated
 | - controllers
-| | - greeter
-| | | - greeter.proto
-| | | - greeter.proto.ts <--- Auto-generated
-| | | - greeter.ctrl.ts
+| | - greeter.controller.ts
 ```
 
 Once your interfaces and configurations are created, you can start building your controller logic.
 
-## Grpc Controller
+NB: you can also manually generate your interfaces from \_.proto files by creating a `.js` file at the root of your project like below. A good practice would be to add the directory containing your generated `.ts` files to `.gitignore` and to add `node generate.js` to the command `npm run build`.
 
-The `@loopback/grpc` component provides you with a handy decorator to implement GRPC Methods within your LoopBack controllers.
+```ts
+const GrpcGenerator = require('@loopback/grpc').GrpcGenerator;
+const path = require('path');
+const fs = require('fs');
 
-`app/controllers/greeter/greeter.ctrl.ts`
+function formatWithColor(message, color) {
+  return `\x1b[${color}m${message}\x1b[0m`;
+}
 
-```js
-import {grpc} from '@loopback/grpc';
-import {Greeter, HelloRequest, HelloReply} from '/greeter.proto';
-/**
- * @class GreeterCtrl
- * @description Implements grpc proto service
- **/
-export class GreeterCtrl implements Greeter.Service {
-    // Tell LoopBack that this is a Service RPC implementation
-    @grpc(Greeter.SayHello)
-    sayHello(request: HelloRequest): HelloReply {
-        return {message: 'Hello ' + request.name};
+const protoTsPath = path.join(process.cwd(), 'src', 'protos-ts');
+try {
+  fs.statSync(protoTsPath);
+} catch (e) {
+  fs.mkdirSync(protoTsPath);
+}
+
+const generator = new GrpcGenerator({
+  compilerOptions: {
+    protoPattern: '**/protos/**/*.proto',
+    // additionalArgs: '--experimental_allow_proto3_optional',
+    tsOutputPath: protoTsPath,
+    protoPath: path.join(process.cwd(), 'src', 'protos'),
+    generate: true,
+    load: false,
+  },
+});
+
+console.log(formatWithColor('Generating proto.ts files from *.proto...', 33));
+generator.execute();
+console.log(formatWithColor('All proto.ts files have been generated', 32));
+```
+
+## gRPC Controller
+
+The `@loopback/grpc` component provides you with a handy decorator to implement gRPC Methods within your LoopBack controllers. The decorator will automatically map the correct calls from the file descriptor, the method name and the controller name. If you want an other suffix than `(Ctrl|Controller)`, you can use the argument `controllerNameRegex`.
+
+`app/controllers/greeter.controller.ts`
+
+```ts
+import {
+  TestRequest,
+  TestResponse,
+  Greeter,
+  protoMetadata,
+} from '../protos-ts/greeter';
+
+class GreeterCtrl implements Greeter {
+  // Tell LoopBack that this is a Service RPC implementation
+  @grpc(protoMetadata.fileDescriptor)
+  async unaryTest(request: TestRequest): Promise<TestResponse> {
+    return {
+      message: 'Hello ' + request.name,
+    };
+  }
+
+  @grpc(protoMetadata.fileDescriptor)
+  async clientStreamTest(
+    request: Observable<TestRequest>,
+  ): Promise<TestResponse> {
+    const names: string[] = [];
+    let error;
+    const observer: PartialObserver<TestRequest> = {
+      next: (value) => names.push(value.name),
+      error: (err) => (error = err),
+    };
+    request.subscribe(observer);
+    await lastValueFrom(request);
+    if (error) {
+      throw error;
     }
+    return {
+      message: names.join(' '),
+    };
+  }
+
+  @grpc(protoMetadata.fileDescriptor)
+  serverStreamTest(request: TestRequest): Observable<TestResponse> {
+    const req = request.name.split(' ');
+    const responseObservable = new Observable<TestResponse>((subscriber) => {
+      subscriber.next({
+        message: req[0],
+      });
+      for (let i = 1; i < req.length; i++) {
+        setTimeout(() => {
+          subscriber.next({
+            message: req[i],
+          });
+        }, i * 200);
+        if (i === req.length - 1) {
+          setTimeout(() => {
+            subscriber.complete();
+          }, i * 200);
+        }
+      }
+    });
+    return responseObservable;
+  }
+
+  @grpc(protoMetadata.fileDescriptor)
+  bidiStreamTest(request: Observable<TestRequest>): Observable<TestResponse> {
+    const responseObservable = new Observable<TestResponse>((subscriber) => {
+      const observer: PartialObserver<TestRequest> = {
+        next: (value) => {
+          subscriber.next({message: `Got ${value.name} !`});
+        },
+        complete: () => subscriber.complete(),
+      };
+      request.subscribe(observer);
+    });
+    return responseObservable;
+  }
 }
 ```
 
 ## Proto Example
 
-`app/controllers/greeter/greeter.proto`
+`app/protos/greeter.proto`
 
-```txt
+```proto
 syntax = "proto3";
 package greeterpackage;
 
 service Greeter {
   // Sends a greeting
-  rpc SayHello (HelloRequest) returns (HelloReply) {}
+  rpc UnaryTest (TestRequest) returns (TestResponse) {}
+  rpc ClientStreamTest (stream TestRequest) returns (TestResponse) {}
+  rpc ServerStreamTest (TestRequest) returns (stream TestResponse) {}
+  rpc BidiStreamTest (stream TestRequest) returns (stream TestResponse) {}
 }
 
 // The request message containing the user's name.
-message HelloRequest {
+message TestRequest {
   string name = 1;
 }
 
 // The response message containing the greetings
-message HelloReply {
+message TestResponse {
   string message = 1;
 }
 ```
 
+## Setting up TLS and mTLS
+
+```ts
+import {GrpcComponentConfig} from '@loopback/grpc';
+
+const grpcConfig: GrpcComponentConfig = {
+  server: {
+    tls: {
+      rootCertPath: 'path/to/root/cert',
+      keyCertPairPaths: [
+        {
+          privateKeyPath: 'path/to/private/key/for/server',
+          certChainPath: 'path/to/cert/chain/for/server',
+        },
+      ],
+    },
+    // set it to false/undefined to disable client certificate verification
+    checkClientCertificate: true,
+  },
+};
+```
+
+### Client side integration
+
+Tests can be a good starting point for your client side integration.
+
 ## Contribute
 
 Get started by either downloading this project or cloning it as follows:
@@ -122,17 +254,16 @@ $ cd loopback4-extension-grpc && npm install
 
 ## Contributions
 
-* [Guidelines](https://github.com/strongloop/loopback-next/wiki/Contributing#guidelines)
-* [Join the team](https://github.com/strongloop/loopback-next/issues/110)
+- [Guidelines](https://github.com/strongloop/loopback-next/wiki/Contributing#guidelines)
+- [Join the team](https://github.com/strongloop/loopback-next/issues/110)
 
 ## Tests
 
 run `npm test` from the root folder.
 
 ## Todo
 
-* Watch for proto changes.
-* Server/Client Streams
+- Maybe watch for proto changes.
 
 ## Contributors
 

src/decorators/README.md

@@ -1,4 +1,3 @@
-
 ## Overview
 
 Decorators provide annotations for class methods and arguments. Decorators use the form `@decorator` where `decorator` is the name of the function that will be called at runtime.
@@ -8,51 +7,62 @@ Decorators provide annotations for class methods and arguments. Decorators use t
 This decorator allows you to annotate a `Controller` class. The decorator will setup a GRPC Service.
 
 **Example**
-````js
+
+```js
 /**
-* Setup gRPC MicroService
-**/
-//myproject/controllers/greeter/Greeter.ts
-//myproject/controllers/greeter/greeter.proto
-//myproject/controllers/greeter/greeter.proto.ts
+ * Setup gRPC MicroService
+ **/
+//myproject/controllers/greeter.controller.ts
+//myproject/protos/greeter/greeter.proto
+//myproject/protos-ts/greeter/greeter.ts
 //Note: greeter.proto.ts is automatically generated from
 //greeter.proto
 import {grpc} from '@loopback/grpc';
-import {Greeter, HelloRequest, HelloReply} from 'greeter.proto';
-class GreeterCtrl implements Greeter.Service {
-  @grpc(Greeter.SayHello)
-  public sayHello(request: HelloRequest): HelloResponse {
-    return { message: 'Hello ' + call.request.name };
+import {
+  Greeter,
+  TestRequest,
+  TestResponse,
+  protoMetadata,
+} from '../protos-ts/greeter';
+class GreeterCtrl implements Greeter {
+  @grpc(protoMetadata.fileDescriptor)
+  async unaryTest(request: TestRequest): Promise<TestResponse> {
+    return {
+      message: 'Hello ' + request.name,
+    };
   }
 }
-````
+```
 
 ## Example Proto File
 
-````proto
+```proto
 syntax = "proto3";
-package awesomepackage;
- 
+package greeterpackage;
+
 service Greeter {
   // Sends a greeting
-  rpc SayHello (HelloRequest) returns (HelloReply) {}
+  rpc UnaryTest (TestRequest) returns (TestResponse) {}
+  rpc ClientStreamTest (stream TestRequest) returns (TestResponse) {}
+  rpc ServerStreamTest (TestRequest) returns (stream TestResponse) {}
+  rpc BidiStreamTest (stream TestRequest) returns (stream TestResponse) {}
 }
 
 // The request message containing the user's name.
-message HelloRequest {
+message TestRequest {
   string name = 1;
 }
 
 // The response message containing the greetings
-message HelloReply {
+message TestResponse {
   string message = 1;
 }
-````
+```
 
 ## Related Resources
 
 You can check out the following resource to learn more about decorators and how they are used in LoopBack Next.
 
 - [TypeScript Handbook: Decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
 - [Decorators in LoopBack](http://loopback.io/doc/en/lb4/Decorators.html)
-- [gRPC in NodeJS](https://grpc.io/docs/quickstart/node.html)
+- [gRPC in NodeJS](https://grpc.io/docs/quickstart/node.html)

src/providers/README.md

@@ -1,3 +1,3 @@
 # Providers
 
-TODO: Need to analyze if this provider is actually valuable...
+TODO: Need to analyze if this provider is actually valuable...