proposals: complete the Falco API proposal

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

proposals/20191030-api.md

@@ -26,7 +26,7 @@ Some examples, already in place, are:
 
 ## Non-Goals
 
--
+- Replace the existing inputs: the **inputs** will be only for new source events users may want to add, initially
 
 ## Proposal
 
@@ -41,37 +41,31 @@ Some examples, already in place, are:
 
 ### Unary services
 
-#### Version
-
-#### Rules
-
-#### Configs
+1. Version
+2. Rules
+3. Configs
 
 ### Streaming (server or client) services
 
-#### Outputs
-
-#### Drops
+1. Outputs
+2. Drops
 
 ### Bidirectional streaming services
 
-#### Inputs
+1. Inputs
 
 ### Architecture
 
 We propose to have:
 - 1 gRPC server
-- 1 service grouping services by their type, so
-  - 1 service for **unary** services
-  - 1 service for **streaming** services
-  - 1 service for **bidirectional** services
+- 1 service grouping services
 
 This translates in having the following set of `proto` files.
 
-- a `.proto` containing the request and response messages for any service - eg., `version.proto`, `outputs.proto` etc.
+- a `.proto` containing the **request** and **response messages** for each service - eg., `version.proto`, `outputs.proto` etc.
 
     For example,
-    ```protobuf
+    ```proto3
     # version.proto
     message request
     {
@@ -94,7 +88,7 @@ This translates in having the following set of `proto` files.
 
 - one or more `.proto` containing the commond models - ie., the already existing `schema.proto` containing source enum, etc.
 
-    ```protobuf
+    ```proto3
     # schema.proto
     enum priority {
       ..
@@ -113,32 +107,12 @@ This translates in having the following set of `proto` files.
 
 - a `.proto` for service definitions
 
-    For example
-    ```protobuf
-    service unary {
+    For example,
+    ```proto3
+    service api {
       rpc version(request) returns (response);
-      ...
-    }
-    service streaming {
       rpc outputs(request) returns (stream response);
       rpc drops(request) returns (stream response);
-    }
-    service bidirectional {
       ...
     }
     ```
-
-#### Benefits
-
-We think this structure makes the implementation easier to write and to maintain because it automatically matches the abstractions - ie., one service by RPC type, a pool of contexts by RPC type - implemented in the code.
-
-#### Limitations
-
-Having more RPCs of the same type (eg., outputs and drops) sharing the same service means:
-
-* they will share the number of simultaneous completion queue requests the gRPC server can handle
-
-This assertion is true in the current implementation.
-Creating one completion queue for every RPC would solve this in case this proves to have a significant impact on the level of performances we desire to achieve.
-
-#### Diagrams