docs(proposals): grpc output design details

Co-Authored-by: Lorenzo Fontana <lo@linux.com>
Signed-off-by: Leonardo Di Donato <leodidonato@gmail.com>

proposals/20190826-grpc-outputs.md

@@ -7,13 +7,15 @@
   * [Goals](#goals)
   * [Non-Goals](#non-goals)
 - [Proposal](#proposal)
-- [Design Details](#design-details)
+  * [Use cases](#use-cases)
+  * [Diagrams](#diagrams)
+  * [Design Details](#design-details)
 
 <!-- tocstop -->
 
 ## Summary
 
-We intend to build a simple gRPC contract and SDKs - eg., [falco#](https://github.com/falcosecurity/falco/issues/785) - to allow users receive and consume the alerts regarding the violated rules.
+We intend to build a simple gRPC contract and SDKs - eg., [falco#785](https://github.com/falcosecurity/falco/issues/785) - to allow users receive and consume the alerts regarding the violated rules.
 
 ## Motivation
 
@@ -29,6 +31,7 @@ The motivation behind this proposal is to design a new output implementation tha
 
 ### Goals
 
+- To decouple the outputs from the Falco code base
 - To design and implement an additional output containing a gRPC client
 - To keep it as simple as possible
 - To have a simple contract interface
@@ -53,41 +56,46 @@ The motivation behind this proposal is to design a new output implementation tha
 
 ## Proposal
 
+### Use cases
 
+- Receive Falco events with a well-defined contract over wire
+- Integrate Falco events with existing alerting/paging mechanisms
+- Integrate Falco events with existing monitoring infrastructures/tools
 
-## Design Details
+### Diagrams
 
-```mermaid
-sequenceDiagram
-    Syscall input ->> Bob: Hello Bob, how are you?
-    K8S audit input ->> Bob: Hello Bob, how are you?
-    Falco engine ->> Bob: Hello Bob, how are you?
+The following sequence diagram illustrates the flow happening for a single rule being matched and the consequent alert through the gRPC output client.
 
-    Bob-->>John: How about you John?
-    Bob--x Alice: I am good thanks!
-    Bob-x John: I am good thanks!
-    Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
+![Single alert sequence diagram](20190826-grpc-output-single-alert-sequence.png)
 
-    Bob-->Alice: Checking with John...
-    Alice->John: Yes... John, how are you?
-```
+### Design Details
 
-```
-Overview
+- When an `Emit` results in an error the response contains and error code and message
+  - Errored emits MUST be handled by Falco by sending the same event in the standard output enriched with the info about the failed `Emit` RPC
+- The RPC communication is asynchronous and non-blocking
+- The RPC communication is made of two (`Output` and `Response`) bi-directional streams
+- `Output` and `Response` messages are correlated through the `id` field
+  - The `id` field is crafted by the gRPC output client
+- The communication is secured using TLS and the builtin client authentication mechanism
 
-The `FalcoOutputService` service defines the Emit RPC call
-that is used to do a bidirectional stream of events between the output server and Falco.
+Here is the proto3 contracts definitions for the client and the server SDK.
 
-The `Output` message is the logical representation of the output model,
-it contains all the elements that Falco emits in an output along with the
-definitions for priorities and sources. It is given as an input to the Emit RPC call.
+```proto3
+// Overview
 
-The `Response` message is the logical representation of the response to an Emit
-RPC call, it contains a message and the information on wether the server returned an error
-while handling the provided `Output`.
+// The `FalcoOutputService` service defines the Emit RPC call
+// that is used to do a bidirectional stream of events between the output server and Falco.
 
-The `Output` and `Response` messages are enriched with an unique identifier that is needed
-because of the asynchronous nature of the streams in order to correlate them.
+// The `Output` message is the logical representation of the output model,
+// it contains all the elements that Falco emits in an output along with the
+// definitions for priorities and sources. It is given as an input to the Emit RPC call.
+
+// The `Response` message is the logical representation of the response to an Emit
+// RPC call, it contains a message and the information on wether the server returned an error
+// while handling the provided `Output`.
+
+// The `Output` and `Response` messages are enriched with an unique identifier that is needed
+// because of the asynchronous nature of the streams in order to correlate them.
 
 service FalcoOutputService {
   rpc Emit (stream Output) returns (stream Response);