Apply review feedback.

Co-authored-by: David Christofas <[email protected]>
Co-authored-by: Jörn Friedrich Dreyer <[email protected]>

docs/ocis/adr/0015-events.md

@@ -17,13 +17,13 @@ geekdocFilePath: 0015-events.md
 
 To be able to implement simple, flexible and independent inter service communication there is the idea to implement an event system in oCIS. A service can send out events which are received by one or more other services. The receiving service can cause different kinds of actions based on the event by utilizing the information that the event carries.
 
-###  Example: EMail Notification
+###  Example: Email Notification
 
-A simple example is the notification feature for oCIS: Users should receive an email when another user shares a file with them. The information, that the file was shared should go out as an event from the share manager, carrying the information which file was shared to which receiver. A potential notification service that really sends out the email listens to these kind of events and sends the email out once on every received event of that specific type.
+A simple example is the notification feature for oCIS: Users should receive an email when another user shares a file with them. The information, that the file was shared should go out as an event from a storage provider or share manager, carrying the information which file was shared to which receiver. A potential notification service that sends out the email listens to these kind of events and sends the email out once on every received event of that specific type.
 
 ## Decision Drivers
 
-- Events are supposed to simplify things and raise flexibility, also considering extensions that are not directly controlled by the ownCloud project.
+- Events are supposed to decouple services and raise flexibility, also considering extensions that are not directly controlled by the ownCloud project.
 - Events should bring flexibility in the implementation of sending and receiving services.
 - Events should not obsolete other mechanisms to communicate, ie. grpc calls.
 - Sending an event has to be as little resource consuming for the sender as possible.
@@ -42,7 +42,7 @@ Reva will get a messaging service that is available to all services within oCIS
 
 All oCIS- and Reva-services can connect to the messaging bus and send so called events. The sender gets an immediate return if handing the event to the message bus was succesful or not.
 
-The sender can not make any assumptions about when the message is delivered to any receiving service, nor if zero, one or many services are listening to that event.
+The sender can not make any assumptions when the message is delivered to any receiving service. Depending on the QoS model (as proposed as alternatives in this ADR) it might even be not guaranteed that the event is delivered at all. Also, the sender can not know if zero, one or many services are listening to that event.
 
 #### Event Data
 
@@ -60,11 +60,12 @@ Events are sent with "At most once" quality of service. That means, if a receive
 
 The described way of inter service communication with events is not transactional. It is not supposed to be, but only provides a lightweight, loosely coupled way to "inform".
 
-If transactions are required, proper GRPC API calls with synchron reply are to be used. Another way would be to build asynchronous flows with request- and reply events in an asynchronous way. That is only recommended for special cases.
+If transactions are required, proper synchronous GRPC API calls should be used. Another way would be to build asynchronous flows with request- and reply events as in [saga pattern](https://microservices.io/patterns/data/saga.html). That is only recommended for special cases.
 
 #### Pros
 - Simple setup
 - Flexible way of connecting services
+- Stateless event queue
 - "State of the art" pattern in microservices architectures
 
 #### Cons
@@ -78,8 +79,9 @@ Exactly as described above, but with a higher service level quality.
 
 #### Pros
 - Better service level: Messages do not get lost.
--
 
+#### Cons
+- Stateful event system with higher cost in terms of compute and storage.
 
 
 ## Decision Outcome