github/falco
1
0
Fork 0
mirror of https://github.com/falcosecurity/falco.git synced 2025-09-20 17:37:43 +00:00
Code Issues Projects Releases Wiki Activity

proposals: complete the Falco API proposal

Browse Source 
Co-Authored-by: Lorenzo Fontana <lo@linux.com>
Signed-off-by: Leonardo Di Donato <leodidonato@gmail.com>
This commit is contained in:
Leonardo Di Donato
2019-10-31 16:42:34 +00:00
committed by Leo Di Donato
parent a64f7faa3c
commit ae52dc4d3b
1 changed files with 14 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
proposals/20191030-api.md
View File

@@ -26,7 +26,7 @@ Some examples, already in place, are:
## Non-Goals ## Non-Goals
- - Replace the existing inputs: the **inputs** will be only for new source events users may want to add, initially
## Proposal ## Proposal
@@ -41,37 +41,31 @@ Some examples, already in place, are:
### Unary services ### Unary services
#### Version 1. Version
2. Rules
#### Rules 3. Configs
#### Configs
### Streaming (server or client) services ### Streaming (server or client) services
#### Outputs 1. Outputs
2. Drops
#### Drops
### Bidirectional streaming services ### Bidirectional streaming services
#### Inputs 1. Inputs
### Architecture ### Architecture
We propose to have: We propose to have:
- 1 gRPC server - 1 gRPC server
- 1 service grouping services by their type, so - 1 service grouping services
- 1 service for **unary** services
- 1 service for **streaming** services
- 1 service for **bidirectional** services
This translates in having the following set of `proto` files. 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, For example,
```protobuf ```proto3
# version.proto # version.proto
message request 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. - one or more `.proto` containing the commond models - ie., the already existing `schema.proto` containing source enum, etc.
```protobuf ```proto3
# schema.proto # schema.proto
enum priority { enum priority {
.. ..
@@ -113,32 +107,12 @@ This translates in having the following set of `proto` files.
- a `.proto` for service definitions - a `.proto` for service definitions
For example For example,
```protobuf ```proto3
service unary { service api {
rpc version(request) returns (response); rpc version(request) returns (response);
...
}
service streaming {
rpc outputs(request) returns (stream response); rpc outputs(request) returns (stream response);
rpc drops(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